From 50ebb4f2e620dad8e1fbca8307b97c5e10e7e6c0 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Tue, 18 Aug 2026 02:14:39 +0200 Subject: docs: settle the desktop client, and draft v6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A design discussion on 2026-08-17 settled Phase 13 and, in doing so, changed four things the spec states. v6 restates only those; v5 stays authoritative for everything it does not touch, per the convention v5 itself used with v4. What changed: * The native shell is **Electron**, not pywebview — structural decision 18 reversed. The SPA depends on Chromium-class APIs (WebRTC, WebCrypto X25519/Ed25519, MSE, Service Workers), so keeping Chromium keeps transport.js, crypto.js, keyderive.js, downloads.js and sw.js *as the client*. A system webview meant reimplementing ~2500-3000 lines. The old "69 % reused" figure was measured against an app.js of ~2600 lines; it is 4586. * A group's content is **several named roots**, not one directory, because the planned video and audio libraries will not live in one folder on one disk. * **Device linking**: one person may hold several devices on a node, admitted by a key the node already pinned and bound by a one-time code the new device generates. Without it a native client is refused where a browser is not, and an account created natively could never be opened in a browser. * **Authorship is authenticated, not asserted** — chat senders sign, uploads have a provable owner, and delete authorization moves from the uploading key to the account. And one rule v5 assumed without writing down: **group-related server state lives on the node.** Verified for multi-root — SwarmSource carries hashes and endpoints, no paths. Also here: the Caddy configuration, which was a snippet in the roadmap that would have broken the SPA (it predates /a// asset versioning and would have 404ed /sw.js, silently killing streamed downloads on Firefox and Safari); and downloads.html, which becomes a security page once a release key exists. Phase 15 was re-read against device linking and is wrong as written: a sender key must be per **device**, never per person, or two devices sharing a chain produce key and nonce reuse — C1 again, one level down. senderkeys.py already fails this silently. Co-Authored-By: Claude Opus 5 --- tmp-decisions.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) (limited to 'tmp-decisions.md') diff --git a/tmp-decisions.md b/tmp-decisions.md index 347d771..76d33d2 100644 --- a/tmp-decisions.md +++ b/tmp-decisions.md @@ -11,10 +11,14 @@ | # | Decision | State | |---|---|---| | D1 | Does the hub keep serving the web UI? | ✅ **DECIDED 2026-08-13 — yes** | -| D2 | Browser extension, native desktop client, or both? | ✅ **DECIDED 2026-08-13 — native client, offered alongside the hub-served SPA** | -| D3 | Transport: aiortc primary, QUIC at parity, TCP+HTTP removed | ✅ Decided 2026-08-13 | +| D2 | Browser extension, native desktop client, or both? | ✅ **DECIDED 2026-08-13 — native client, offered alongside the hub-served SPA.** Shell revised 2026-08-17: **Electron**, see `docs/desktop-client-v1.md` | +| D3 | Transport: aiortc primary, QUIC at parity, TCP+HTTP removed | ✅ Decided 2026-08-13. Unchanged for the **node**; the desktop client uses Chromium's WebRTC rather than aiortc, and QUIC via a Python sidecar | | D4 | Hub minimization (old Phase 12) | ⏸️ **Deferred, may be dropped** | +> **2026-08-17 — the browser-extension options are no longer live.** 12.2 (signed digest +> of the served bundle) is what Option A needed, and it remains scheduled; nothing else +> from A or B is planned. The desktop client is the answer to T3 for users who want one. + **What was decided.** The hub keeps serving the web UI — that is the zero-install path and it stays. A native desktop client is offered *in addition*, not as a replacement. Hub minimization is off the critical path and may be dropped entirely. @@ -103,10 +107,24 @@ hub operator does not control**. Manifest V3 forbids remote code, which works in the structure enforces exactly what we want. Keys live in extension storage, isolated from page JS. Moderate effort. -**Option C — Native desktop client (pywebview + aiortc)** ← **CHOSEN** +**Option C — Native desktop client** ← **CHOSEN** Phase 13. Full control, durable keys in an OS keystore, QUIC, hub-less access, best UX. Highest effort, and the security argument depends on 18.7. +> **Shell revised 2026-08-17: Electron, not pywebview** (+ an optional Python sidecar for +> `group://` over QUIC). See `docs/desktop-client-v1.md` §2. The comparison table below +> was written against pywebview and **two of its rows are wrong for the chosen shell**: +> +> - *Browser sandbox* — Electron with `sandbox` and `contextIsolation` **keeps** the +> Chromium renderer sandbox. The row reads "❌ None (partial under Flatpak)"; that was +> WebKitGTK's property, not native's. +> - *Crypto available* — the client keeps WebCrypto **and** gains local Argon2id/ChaCha20 +> in the main process; the row implied WebCrypto is lost with the browser engine. +> +> The row that gets *worse*: **patch velocity**. "You own it" is more true of Chromium +> than of a distro-maintained WebKitGTK, and the renderer parses attacker-controlled +> content from nodes. That is the real cost and it is accepted deliberately. + ### Comparison | | Hub-served SPA (today) | A: extension verifies | B: extension ships UI | C: native desktop | -- cgit v1.2.3