v0.1: HTTP+SSE broadcast bus + phone web UI + Linux client

Single Go module with two binaries (server, client) and an embedded phone UI. MVP transport is HTTP POST → SSE fanout; the roadmap calls for upgrading to WebRTC P2P with Sign in with Apple for identity, mDNS for discovery, and OS clipboard hooks. - server/: Go HTTP server, embedded index.html, broadcast bus with short replay history, SSE stream endpoint, single-binary deploy. - client/: subscribes to SSE feed and prints messages; -send for one-shot publish from CLI. No OS clipboard touched yet (v0.5). - web/index.html: dark phone-first UI, paste-clipboard button (uses navigator.clipboard.readText), live feed of incoming messages via EventSource. This commit is intentionally tiny — it proves the end-to-end shape so the WebRTC/SiwA/mDNS pieces can be added incrementally without restructuring. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 23:53:31 -05:00
commit b8f168df54
6 changed files with 502 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,8 @@
+/tether-server
+/tether-client
+/bin/
+*.exe
+*.dll
+*.so
+*.dylib
+.DS_Store
--- a/README.md
+++ b/README.md
@@ -0,0 +1,87 @@
+# tether
+
+Phone ↔ laptop clipboard relay. **v0.1 / MVP.**
+
+Today this is an HTTP+SSE broadcast bus. The roadmap is what makes it
+interesting: WebRTC for true P2P, Sign in with Apple for cross-device
+identity, mDNS for same-LAN discovery, end-to-end encryption baked in.
+
+```
+phone (web UI)              tether-server                tether-client
+─────────────               ─────────────                ──────────────
+type/paste                  HTTP+SSE relay               Linux/Mac/Win
+  │                              │                              │
+  └─── POST /api/send ──────────▶│                              │
+                                 ├──── event: clipboard ───────▶│
+                                 │                              ▼
+                                 │                          stdout / OS
+                                 │                          clipboard
+                                 │◀──── POST /api/send ─────────┘
+                                 ▼
+                          web UI shows it
+```
+
+## Quick start
+
+```bash
+go run ./server
+# in another terminal
+go run ./client -server http://localhost:8765
+
+# send a one-shot message from CLI:
+go run ./client -server http://localhost:8765 -send "hello"
+```
+
+Then open `http://localhost:8765/` on your phone (same network) and try
+the buttons.
+
+## Pieces
+
+- `server/` — single Go binary. Embedded HTML page. Exposes:
+  - `GET /` — phone UI
+  - `POST /api/send` — accept a message
+  - `GET /api/stream` — SSE feed of every published message
+  - `GET /healthz`
+- `client/` — CLI client. Subscribes to `/api/stream`, prints received
+  messages to stdout. `-send` for one-shot send.
+- `server/web/index.html` — phone UI (paste, send, live feed of incoming).
+
+## Roadmap
+
+| Phase | What | Why |
+|---|---|---|
+| **v0.1 (now)** | HTTP+SSE relay, single broadcast bus | Prove the shape end-to-end |
+| v0.2 | mDNS service advertisement, QR pairing | Zero-config discovery |
+| v0.3 | WebRTC data channel (Pion) — clients negotiate P2P after seeing each other via the server's signaling | True low-latency E2E (DTLS) |
+| v0.4 | Sign in with Apple OAuth → stable `sub` ties multiple devices to one trust circle | Identity without account/password |
+| v0.5 | OS clipboard hook on client (read + write) — phone copy → laptop paste appears automatically | The actual Universal-Clipboard UX |
+| v0.6 | File drop (large blob over WebRTC), encrypted at-rest history | Snapdrop-like UX bundled in |
+| v1.0 | macOS / Windows clients, push notifications when off-network, packaged installers | Product |
+
+## Why E2E by default
+
+WebRTC data channels mandate DTLS. Once we move from SSE relay (v0.1) to
+P2P data channels (v0.3+), the server only ever sees encrypted bytes
+(and only during signaling — not for the data itself). That's free
+end-to-end encryption, modeled on Apple's Continuity but using
+standardized protocols.
+
+## Why Sign in with Apple
+
+~80% of Windows users also own an iPhone. SiwA gives us a free,
+privacy-respecting identity provider that returns a stable per-app
+subject ID. Devices that authenticate to the same `sub` are in the same
+trust circle automatically. No passwords, no per-app account.
+
+## What this isn't
+
+- Not a Snapdrop clone (no file drop yet)
+- Not KDE Connect (no OS integration yet)
+- Not Pushbullet (no server-side persistence)
+- Not yet WebRTC (v0.1 is HTTP relay)
+
+But the foundation is right.
+
+## License
+
+MIT
--- a/client/main.go
+++ b/client/main.go
@@ -0,0 +1,99 @@
+// tether-client: connects to a tether-server, prints messages to stdout.
+// MVP — does not yet touch the OS clipboard.
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+type Message struct {
+	Text   string `json:"text"`
+	Source string `json:"source,omitempty"`
+	TS     int64  `json:"ts"`
+}
+
+func main() {
+	server := flag.String("server", "http://localhost:8765", "tether-server base URL")
+	label := flag.String("label", "linux-client", "X-Tether-Client label")
+	sendText := flag.String("send", "", "send this text and exit (otherwise listen)")
+	flag.Parse()
+
+	if *sendText != "" {
+		send(*server, *label, *sendText)
+		return
+	}
+
+	for {
+		if err := listen(*server, *label); err != nil {
+			log.Printf("stream error: %v — reconnecting in 3s", err)
+			time.Sleep(3 * time.Second)
+		}
+	}
+}
+
+func send(server, label, text string) {
+	body, _ := json.Marshal(Message{Text: text, Source: label})
+	req, _ := http.NewRequest("POST", server+"/api/send", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Tether-Source", label)
+	r, err := http.DefaultClient.Do(req)
+	if err != nil {
+		log.Fatalf("send: %v", err)
+	}
+	defer r.Body.Close()
+	if r.StatusCode >= 300 {
+		log.Fatalf("send: HTTP %d", r.StatusCode)
+	}
+	fmt.Println("sent.")
+}
+
+func listen(server, label string) error {
+	req, _ := http.NewRequest("GET", server+"/api/stream", nil)
+	req.Header.Set("X-Tether-Client", label)
+	r, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer r.Body.Close()
+	if r.StatusCode != 200 {
+		return fmt.Errorf("HTTP %d", r.StatusCode)
+	}
+	fmt.Fprintf(os.Stderr, "tether-client: connected to %s as %q\n", server, label)
+	sc := bufio.NewScanner(r.Body)
+	sc.Buffer(make([]byte, 1024*1024), 1024*1024)
+	var ev, data string
+	for sc.Scan() {
+		line := sc.Text()
+		switch {
+		case strings.HasPrefix(line, "event: "):
+			ev = strings.TrimPrefix(line, "event: ")
+		case strings.HasPrefix(line, "data: "):
+			data = strings.TrimPrefix(line, "data: ")
+		case line == "":
+			if ev == "clipboard" && data != "" {
+				var m Message
+				if err := json.Unmarshal([]byte(data), &m); err == nil {
+					ts := time.UnixMilli(m.TS).Format("15:04:05")
+					fmt.Printf("\n──────  %s  from %s  ──────\n%s\n", ts, m.Source, m.Text)
+				}
+			}
+			ev, data = "", ""
+		case strings.HasPrefix(line, ": "):
+			// keepalive — ignore
+		}
+	}
+	if err := sc.Err(); err != nil && err != io.EOF {
+		return err
+	}
+	return nil
+}
--- a/go.mod
+++ b/go.mod
@@ -0,0 +1,3 @@
+module github.com/pecord/tether
+
+go 1.22
--- a/server/main.go
+++ b/server/main.go
@@ -0,0 +1,153 @@
+// tether-server: HTTP+SSE relay for phone↔client clipboard sync.
+// MVP: single broadcast bus, no auth, no rendezvous, no WebRTC yet.
+package main
+
+import (
+	"embed"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io/fs"
+	"log"
+	"net/http"
+	"sync"
+	"time"
+)
+
+//go:embed web/index.html
+var webFS embed.FS
+
+type Message struct {
+	Text   string `json:"text"`
+	Source string `json:"source,omitempty"`
+	TS     int64  `json:"ts"`
+}
+
+type bus struct {
+	mu      sync.Mutex
+	clients map[chan Message]string // chan → label
+	history []Message               // last N (for new subscribers)
+}
+
+func newBus() *bus {
+	return &bus{clients: map[chan Message]string{}}
+}
+
+func (b *bus) subscribe(label string) chan Message {
+	ch := make(chan Message, 16)
+	b.mu.Lock()
+	b.clients[ch] = label
+	// replay last few so newcomers see something
+	for _, m := range b.history {
+		select {
+		case ch <- m:
+		default:
+		}
+	}
+	b.mu.Unlock()
+	return ch
+}
+
+func (b *bus) unsubscribe(ch chan Message) {
+	b.mu.Lock()
+	delete(b.clients, ch)
+	b.mu.Unlock()
+	close(ch)
+}
+
+func (b *bus) publish(m Message) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.history = append(b.history, m)
+	if len(b.history) > 10 {
+		b.history = b.history[len(b.history)-10:]
+	}
+	for ch := range b.clients {
+		select {
+		case ch <- m:
+		default: // drop on slow consumer
+		}
+	}
+}
+
+func main() {
+	addr := flag.String("addr", ":8765", "listen address")
+	flag.Parse()
+
+	b := newBus()
+
+	// Serve embedded HTML
+	sub, _ := fs.Sub(webFS, "web")
+	mux := http.NewServeMux()
+	mux.Handle("/", http.FileServer(http.FS(sub)))
+
+	// POST /api/send — accept a message, broadcast to subscribers
+	mux.HandleFunc("/api/send", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "POST only", http.StatusMethodNotAllowed)
+			return
+		}
+		var m Message
+		if err := json.NewDecoder(r.Body).Decode(&m); err != nil {
+			http.Error(w, "bad json", http.StatusBadRequest)
+			return
+		}
+		if m.Source == "" {
+			m.Source = r.Header.Get("X-Tether-Source")
+			if m.Source == "" {
+				m.Source = "phone"
+			}
+		}
+		m.TS = time.Now().UnixMilli()
+		b.publish(m)
+		log.Printf("publish: %s len=%d", m.Source, len(m.Text))
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	// GET /api/stream — SSE feed of all published messages
+	mux.HandleFunc("/api/stream", func(w http.ResponseWriter, r *http.Request) {
+		fl, ok := w.(http.Flusher)
+		if !ok {
+			http.Error(w, "no flusher", http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.Header().Set("Cache-Control", "no-cache")
+		w.Header().Set("Connection", "keep-alive")
+		w.Header().Set("X-Accel-Buffering", "no")
+
+		label := r.Header.Get("X-Tether-Client")
+		if label == "" {
+			label = r.RemoteAddr
+		}
+		ch := b.subscribe(label)
+		defer b.unsubscribe(ch)
+		log.Printf("subscribe: %s", label)
+
+		// keepalive
+		ka := time.NewTicker(30 * time.Second)
+		defer ka.Stop()
+
+		for {
+			select {
+			case <-r.Context().Done():
+				log.Printf("unsubscribe: %s", label)
+				return
+			case m := <-ch:
+				bs, _ := json.Marshal(m)
+				fmt.Fprintf(w, "event: clipboard\ndata: %s\n\n", bs)
+				fl.Flush()
+			case <-ka.C:
+				fmt.Fprintf(w, ": keepalive\n\n")
+				fl.Flush()
+			}
+		}
+	})
+
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("ok"))
+	})
+
+	log.Printf("tether-server listening on %s", *addr)
+	log.Fatal(http.ListenAndServe(*addr, mux))
+}
--- a/server/web/index.html
+++ b/server/web/index.html
@@ -0,0 +1,152 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover" />
+<meta name="theme-color" content="#0a0a0a" />
+<title>tether</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; height: 100%; }
+  body {
+    font: 15px -apple-system, "SF Pro Text", system-ui, sans-serif;
+    background: #0a0a0a; color: #e5e5e5;
+    display: flex; flex-direction: column;
+    padding: 18px 16px env(safe-area-inset-bottom);
+    gap: 14px;
+  }
+  header { display: flex; align-items: baseline; gap: 8px; }
+  h1 { margin: 0; font-size: 22px; font-weight: 600; letter-spacing: -0.5px; }
+  .tag { font-size: 11px; color: #888; letter-spacing: 0.5px; text-transform: uppercase; }
+  .row { display: flex; flex-direction: column; gap: 6px; }
+  label { font-size: 11px; color: #888; letter-spacing: 0.4px; text-transform: uppercase; }
+  textarea {
+    width: 100%; min-height: 130px; resize: vertical;
+    font: 15px -apple-system, ui-monospace, "SF Mono", monospace;
+    background: #161616; color: #f5f5f5;
+    border: 1px solid #232323; border-radius: 10px;
+    padding: 12px; outline: none;
+  }
+  textarea:focus { border-color: #3a3a3a; }
+  .actions { display: flex; gap: 8px; }
+  button {
+    flex: 1; padding: 12px 16px; font: 600 14px -apple-system, system-ui, sans-serif;
+    background: #1a1a1a; color: #f5f5f5;
+    border: 1px solid #2a2a2a; border-radius: 10px;
+    cursor: pointer; transition: background 0.15s;
+  }
+  button.primary { background: #4f46e5; border-color: #6366f1; }
+  button.primary:active { background: #4338ca; }
+  button:active { background: #232323; }
+  .status {
+    font-size: 13px; color: #888;
+    padding: 8px 12px; background: #131313;
+    border: 1px solid #1f1f1f; border-radius: 8px;
+    min-height: 38px; display: flex; align-items: center;
+  }
+  .status.ok { color: #4ade80; }
+  .status.err { color: #f87171; }
+  .feed { display: flex; flex-direction: column; gap: 6px; }
+  .feed h2 { font-size: 11px; color: #888; letter-spacing: 0.5px; text-transform: uppercase; margin: 0; }
+  .msg {
+    background: #131313; border: 1px solid #1f1f1f; border-radius: 8px;
+    padding: 10px 12px; font: 13px ui-monospace, "SF Mono", monospace;
+    color: #d4d4d4; white-space: pre-wrap; word-break: break-word;
+    max-height: 200px; overflow: auto;
+  }
+  .meta { font-size: 11px; color: #666; margin-top: 4px; }
+  footer {
+    margin-top: auto; padding-top: 8px;
+    font-size: 11px; color: #555; text-align: center;
+  }
+  footer a { color: #888; text-decoration: none; }
+</style>
+</head>
+<body>
+<header>
+  <h1>tether</h1>
+  <span class="tag">phone ↔ laptop</span>
+</header>
+
+<div class="row">
+  <label for="out">send to laptop</label>
+  <textarea id="out" placeholder="paste or type something…"></textarea>
+  <div class="actions">
+    <button id="pasteBtn">paste clipboard</button>
+    <button class="primary" id="sendBtn">send →</button>
+  </div>
+</div>
+
+<div class="status" id="status">idle</div>
+
+<div class="feed">
+  <h2>received from laptop</h2>
+  <div id="incoming"></div>
+</div>
+
+<footer>
+  <a href="https://gitea.pecord.io/pecord/tether">tether on gitea</a> · v0.1
+</footer>
+
+<script>
+  const $ = (id) => document.getElementById(id);
+  const status = (msg, cls) => {
+    const s = $("status");
+    s.textContent = msg;
+    s.className = "status" + (cls ? " " + cls : "");
+  };
+
+  $("pasteBtn").addEventListener("click", async () => {
+    try {
+      const text = await navigator.clipboard.readText();
+      $("out").value = text;
+      status("pasted from clipboard", "ok");
+    } catch (e) {
+      status("clipboard read denied — paste manually", "err");
+    }
+  });
+
+  $("sendBtn").addEventListener("click", async () => {
+    const text = $("out").value;
+    if (!text) { status("empty", "err"); return; }
+    status("sending…");
+    try {
+      const r = await fetch("/api/send", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text }),
+      });
+      if (r.ok) {
+        status("delivered ✓", "ok");
+      } else {
+        status("server returned " + r.status, "err");
+      }
+    } catch (e) {
+      status("network error", "err");
+    }
+  });
+
+  // SSE: receive incoming messages from clients
+  function connectFeed() {
+    const es = new EventSource("/api/stream");
+    es.addEventListener("clipboard", (ev) => {
+      try {
+        const m = JSON.parse(ev.data);
+        const el = document.createElement("div");
+        el.className = "msg";
+        el.textContent = m.text;
+        const meta = document.createElement("div");
+        meta.className = "meta";
+        meta.textContent = (m.source || "client") + " @ " + new Date(m.ts).toLocaleTimeString();
+        el.appendChild(meta);
+        const feed = $("incoming");
+        feed.insertBefore(el, feed.firstChild);
+      } catch (e) {}
+    });
+    es.onerror = () => setTimeout(connectFeed, 2000);
+  }
+  connectFeed();
+</script>
+</body>
+</html>