# flit

Self-hosted, ephemeral, end-to-end encrypted file transfer between your own devices. Think AirDrop — but cross-platform, self-hosted, and accessible from any browser.

> Self-hosted — deploy your own instance, see [Self-hosting](#self-hosting) below.

---

## What it is

flit solves a specific, annoying problem: getting a file from one of your devices to another right now, with no friction and nothing left behind on a server.

It is deliberately not a replacement for [Zipline](https://github.com/diced/zipline) or similar tools — those are great for "upload once, share via link." flit is for point-to-point transfers between devices you own: desktop to phone, homelab box to laptop, anything to anything.

- No accounts. No upload limits. No files touch a server disk.
- Works across networks (home WiFi ↔ mobile data) via a self-hosted TURN relay.
- Encrypted end-to-end with keys that never leave your devices.
- Remembered devices reconnect directly — no QR re-scan, no invite link.
- Multi-file send: select multiple files at once, each offered and accepted independently.
- Auto-downloads on the receiver side — no "click to save" step.
- In-app QR scanner (Chrome/Android) — scan the sender's QR without leaving flit.
- Android share sheet integration — "Share → flit" works from Photos, Files, any app.
- One-way folder sync (`flit watch`) — drop a file into a watched folder, it gets pushed to a trusted peer automatically, no manual send.

---

## How it works

### Architecture

```
Device A ──┐                          ┌── Device B
           │   WebSocket signaling    │
           └──► Anchor (VPS) ◄───────┘
                    │
                    │  SDP/ICE only — no file data
                    ▼
              Direct WebRTC P2P  ──────────────────────── (preferred)
              TURN relay (coturn) ─────────────────────── (fallback, still E2E encrypted)
```

Three components:

**Signaling anchor** — a lightweight Go WebSocket server (reused from [waste-go](../waste-go)). It brokers the WebRTC handshake: peers join a room by hashed name, exchange SDP offers/answers and ICE candidates through the anchor, then the anchor steps out of the way. No file data ever passes through it.

**TURN relay** — a coturn instance used as a fallback when direct peer-to-peer ICE fails (common across mobile networks and CGNAT). Data is end-to-end encrypted before entering the relay — coturn sees only ciphertext.

**Clients** — a PWA (primary) and a Go CLI (headless/homelab).

### Security model

Each device generates an **Ed25519 keypair** on first run. The hex-encoded public key is the device's permanent identity (`id`). This identity is stored in `localStorage` (PWA) or `~/.flit/` (CLI) and never leaves the device.

Pairing uses [yaw/2.1](PROTOCOL.md) forward-secret signaling, trimmed for flit's 1:1 ephemeral use case:

1. Connecting peers exchange **ephemeral X25519 keys** (`ekey`) signed with their Ed25519 identity keys over the sealed signaling channel — this is what actually authenticates "the device on the other end is who the QR said it was."
2. Once the WebRTC data channel opens, each side sends a **`hello`** message confirming its identity, plus a best-effort signature binding it to the session's DTLS fingerprint when both sides report that fingerprint under a hash algorithm flit can parse. `verified` status rests on step 1 (the authenticated sealed exchange) and `hello.id` matching it — not on the fingerprint signature, which different WebRTC stacks may report under different hash algorithms (WebKit: sha-512, Chromium/pion: sha-256) and so can't be relied on to match even between two legitimate peers.
3. File data flows over the WebRTC data channel — encrypted by DTLS, with the identity already confirmed by step 1.

The anchor never sees plaintext message content — it only routes sealed (encrypted) blobs by peer id and hashed room name.

### Pairing flows

**Ephemeral (QR)** — for first-time pairing or one-off transfers to unrecognised devices:

1. Sender opens flit → "Invite new" → "Show QR to pair." A 128-bit random room code is generated and encoded in a `flit:` invite string, displayed as a QR.
2. Receiver scans the QR using the in-app scanner ("Scan QR") or pastes the `flit:` string manually → "Join."
3. Both peers connect to the anchor under the hashed room name, complete the E2E handshake, and exchange files.
4. After connecting, either side can tap "Remember this device" and assign a nickname ("home", "phone") to the peer's identity.

**Trusted device (direct reconnect)** — for devices that have been previously paired:

1. flit opens to the "Known devices" screen by default (falls back to "Invite new" if none exist yet).
2. Tap **Connect** next to a remembered device — no QR, no invite string.
3. Both sides independently compute the same deterministic room name from their two peer IDs (`flit-pair:<sorted(idA, idB)>` in `pwa/src/pairing/ephemeral.ts`), join it pinned to each other's identity, and the handshake completes automatically.

The room is pinned to the trusted peer's identity — any other device that somehow joins the same derived room is silently ignored. Trusted peers can be renamed or forgotten at any time from the Known devices list.

---

## Clients

### PWA

The primary client. Runs in any Chromium-based browser and is installable as a PWA on Android home screen. Once installed, it registers as a **Web Share Target** — "Share → flit" in any Android app's share sheet will open flit with the file pre-loaded, ready to send after pairing.

Features:
- Known devices tab (direct reconnect) and Invite new tab (QR / paste)
- In-app QR scanner via native `BarcodeDetector` API (no library, Chrome/Android)
- Multi-file send with per-file accept/reject on the receiver, "Accept all" when multiple arrive simultaneously
- Real-time send and receive progress bars
- Auto-download on receipt — files save immediately without a manual tap
- Trusted peer nicknames, rename, forget

**Built with:** React, TypeScript, Vite, libsodium-wrappers (crypto), WebRTC (native browser API).

### CLI (`cli/`)

For headless machines (homelab boxes, servers) that can't run a browser.

```
flit send path/to/file.tar.gz     # print QR + invite, wait for peer, send
flit recv "flit:eyJhbmNob3..."    # join from invite string, accept file
flit daemon                        # persistent receiver for trusted peers
flit watch [--dry-run]             # watch folders, auto-push new files to trusted peers
```

**Built with:** Go, pion/webrtc, libsodium (via nhooyr.io/websocket + internal crypto).

### Daemon mode

`flit daemon` is an always-on receiver — it stays connected to a list of trusted peers and automatically accepts any file they send, saving to a configured directory. Useful for a homelab node that acts as a drop-point: send from phone or laptop, file appears on the home box without any interaction.

Config lives at `~/.flit/daemon.toml`:

```toml
signal_url   = "wss://your-anchor.example.com/ws"
turn_url     = "turn:your-anchor.example.com:3478"  # optional
turn_secret  = ""                                    # optional
download_dir = "~/flit-inbox"

[[peers]]
id    = "aabbccddeeff..."   # hex Ed25519 pubkey — from PWA Known devices list
label = "phone"             #   or from "peer connected" line in flit send output

[[peers]]
id    = "112233445566..."
label = "laptop"
```

Copy `cli/daemon.toml.example` to `~/.flit/daemon.toml` to get started. The daemon runs one goroutine per peer, reconnects automatically with exponential backoff (2s → 30s cap) if the peer drops or the anchor restarts, and logs all activity to stdout — suitable for a tmux session or systemd unit.

**Topology note:** the daemon is just a third peer with its own identity. If you run it on a home box and trust it from both your phone and laptop, all three devices can reach each other directly — phone→laptop still works without the home box involved. The daemon adds an always-on rendezvous point, not a relay.

**Bootstrapping:** to get a peer's `id`, pair once via QR (`flit send` / PWA "Invite new") and copy the hex ID from the "peer connected" log line, or read it from the PWA's Known devices list after tapping "Remember this device."

### Watch mode

`flit watch` is the send-side sibling of `flit daemon`: it watches one or more local folders and automatically pushes new or changed files to a specific trusted peer — no manual `flit send`, no QR, no per-file interaction. It's **one-way sync only** (source → destination, push only) — deliberately not a general bidirectional sync tool, and it never propagates deletes.

The receiving side needs no changes: an already-running `flit daemon`, configured with the watcher's device as a trusted peer, already does the right thing on receipt.

Config lives at `~/.flit/watch.toml`:

```toml
signal_url = "wss://your-anchor.example.com/ws"
turn_url   = ""   # optional
turn_secret = ""  # optional

[[watch]]
dir = "/home/user/backups/documents"
peer_id = "<hex Ed25519 pubkey of the destination device>"
peer_label = "home-server"
pattern = "*.pdf,*.docx"   # optional glob include-list; default "*" if omitted
stable_after = "10s"       # optional quiet period before considering a file ready
```

Multiple `[[watch]]` blocks are allowed — different folders can go to different peers, or the same peer (entries sharing a `peer_id` share a single connection).

Copy `cli/watch.toml.example` to `~/.flit/watch.toml` to get started. Notes on behavior:

- **Startup reconciliation** — on start, before subscribing to filesystem events, `flit watch` walks each `dir` and diffs it against local state, so anything that changed while the watcher wasn't running gets picked up (not just live events going forward).
- **Debounce (`stable_after`)** — a file is only considered ready to send after this quiet period has passed since its last write, so a large file being actively written isn't offered mid-write.
- **State tracking** — one JSON state file per `[[watch]]` entry lives in `~/.flit/watch-state/`, recording what's been sent. If a send fails partway (peer disconnects mid-transfer), the file is retried on the next successful connection — no separate retry logic needed. Losing this state is harmless (worst case: the whole directory gets re-sent) but not something to engineer around.
- **`flit watch --dry-run`** walks the configured directories and prints what *would* be sent, without connecting to anything — use it to sanity-check a new `watch.toml` before it goes live.
- **`pattern` should be as narrow as your use case allows.** `*` is the default if omitted, but an unconstrained watch on a broad directory turns "sync my documents" into "sync everything that ever lands in this tree." There's no per-file confirmation in watch mode — the directory and pattern in `watch.toml` are the only safety knob.
- Reconnects with the same exponential backoff (2s → 30s cap) as daemon mode, and reuses the same trusted-peer identity model — a `peer_id` here is the same kind of already-known device as anything in the PWA's Known devices list or `daemon.toml`.

---

## Self-hosting

flit has no server of its own. The PWA is a static file bundle served by `npx serve`. For signaling and TURN relay it requires a running [waste-go](https://repo.explewd.com/explewd/waste-go) anchor.

### Deploy scripts

The deploy scripts contain your SSH target and are gitignored — create them locally from these templates:

**`deploy-pwa.sh`** — build and rsync `pwa/dist/` to the host:
```bash
#!/usr/bin/env bash
set -euo pipefail

HOST="user@your-host.example.com"
REMOTE_DIR="~/flit-www"

echo "→ building PWA…"
"$(dirname "$0")/build-pwa.sh"

echo "→ syncing to $HOST:$REMOTE_DIR"
rsync -azv --delete \
    --exclude='config.js' \
    pwa/dist/ "$HOST:$REMOTE_DIR/"

echo "✓ done"
```

**`serve-pwa.sh`** — (re)start `npx serve` on the host:
```bash
#!/usr/bin/env bash
set -euo pipefail

HOST="user@your-host.example.com"
REMOTE_DIR="~/flit-www"
REMOTE_LOG="~/flit-www.log"
REMOTE_PID="~/flit-www.pid"
PORT=3002          # pick a free port; point your reverse proxy here

ssh "$HOST" bash <<EOF
  if [ -f $REMOTE_PID ]; then
    kill \$(cat $REMOTE_PID) 2>/dev/null || true
    rm -f $REMOTE_PID
  fi
  echo "[\$(date)] starting" >> $REMOTE_LOG
  nohup npx serve -s $REMOTE_DIR -l $PORT >> $REMOTE_LOG 2>&1 &
  echo \$! > $REMOTE_PID
  echo "→ started (pid \$(cat $REMOTE_PID))"
EOF
```

`config.js` is gitignored so host-specific config survives redeployment (`rsync --exclude='config.js'`). On a fresh host, seed it once:

```bash
cp pwa/public/config.js.example pwa/public/config.js
# fill in your anchor URL, then:
scp pwa/public/config.js user@your-host.example.com:~/flit-www/config.js
```

`config.js` sets the anchor and TURN URLs at runtime:

```js
window.FLIT_CONFIG = {
  signalURL: 'wss://your-anchor.example.com/ws',
  turnURL:   'turn:your-anchor.example.com:3478',
  turnCredentialsURL: 'https://your-anchor.example.com/turn-credentials',
}
```

Your reverse proxy should forward `flit.<domain>` → `localhost:<PORT>` (the port chosen above).

### CI / releases

`.gitea/workflows/build.yml` builds the PWA on `v*` tag push and publishes `flit-pwa.tar.gz` as a Gitea release artifact. Requires a `RELEASE_TOKEN` secret in the repo settings.

---

## Development

```bash
cd pwa
npm install
npm run dev      # Vite dev server at localhost:5173

# Build for production
npm run build    # output to pwa/dist/

# CLI
export FLIT_SIGNAL_URL=wss://your-anchor.example.com/ws
export FLIT_TURN_URL=turn:your-anchor.example.com:3478   # optional
export FLIT_TURN_SECRET=your-coturn-secret               # optional
cd cli
go run ./cmd/flit send path/to/file
```

The PWA reads its anchor URL from `public/config.js` at runtime. The CLI reads `FLIT_SIGNAL_URL` from the environment. Both are gitignored/unset by default — you supply your own anchor.

---

## Protocol

flit speaks a trimmed subset of [yaw/2.1](PROTOCOL.md). Dropped vs. waste-go: chat, presence, multi-peer mesh, file browsing. Kept: Ed25519 identity, forward-secret `ekey` handshake, `hello` verification, `file-offer`/`file-accept`/`file-cancel`, chunked binary DataChannel transfer.

---

## Changelog

### Scaffolding
- Repo scaffold: PWA (React/TS/Vite) + Go CLI skeleton
- Go CLI: `flit send` / `flit recv`, Ed25519 identity in `~/.flit/`, terminal QR output
- PWA: ephemeral QR pairing, yaw/2.1 signaling, WebRTC file transfer, Web Share Target manifest

### Deployment
- `build-pwa.sh`, `deploy-pwa.sh`, `serve-pwa.sh` — mirrors waste-go's deploy pattern
- Static files served via `npx serve` on port 3002 of the VPS, fronted by Nginx Proxy Manager
- `.gitea/workflows/build.yml` — builds PWA on `v*` tag, publishes `flit-pwa.tar.gz` as a Gitea release artifact
- `pwa/public/config.js` runtime config excluded from deploys (host-specific override pattern)

### Core pairing and transfer
- Fixed silent failure when `window.FLIT_CONFIG` missing (error banner, async error surfacing)
- RTCPeerConnectionState surfaced in UI (`checking` / `connected` / `failed`) — previously stuck silently on "Connecting…"
- Sender-side progress events and progress bar (fix: synchronous chunk loop blocked React renders — added `setTimeout(0)` yield per chunk)
- `peerId` now set at connection time, not only on first file offer — fixed "Remember this device" silently doing nothing

### Trusted devices / known peer reconnect
- Persistent keyring (`pwa/src/pairing/keyring.ts`) — Ed25519 peer IDs stored in `localStorage` with user-assigned nicknames
- `pairRoomName(idA, idB)` — deterministic shared room derived from sorted peer IDs; both sides compute independently, no QR needed
- Known devices tab: default view when trusted peers exist; Connect / Rename / Forget per device
- Nickname prompt on "Remember this device" (previously auto-used key prefix)
- `connected` event now carries `peerId` so the keyring button works immediately after handshake, not only after a file offer

### Multi-file and UX
- Multi-file receive: offer queue (previously a single slot — second offer replaced first); "Accept all (N)" button when multiple arrive simultaneously
- Auto-download on receipt via programmatic `<a>.click()` — no manual tap required
- In-app QR scanner using native `BarcodeDetector` API (no library); camera overlay with cancel; graceful fallback message on unsupported browsers
- Received files list retained below the auto-download as a fallback link

### Visual design
- Full restyle to terminal aesthetic matching waste-go's visual identity: `#080808` bg, `#00e87a` green accent, JetBrains Mono throughout
- `manifest.json`: fixed missing PNG icon references (replaced with SVG), corrected `theme_color` from blue → green
- Apple PWA meta tags added (`apple-mobile-web-app-capable`, status bar style, title)
- Progress bars with green glow, `> flit.` monospace header, `@ nickname` device labels, `// comment` style hints

### CLI daemon
- `flit daemon` subcommand — persistent receiver for trusted peers, reads `~/.flit/daemon.toml`
- TOML config: `signal_url`, `turn_url`, `turn_secret`, `download_dir`, `[[peers]]` list
- One goroutine per peer, exponential backoff reconnect (2s → 30s)
- `OnDisconnected` callback added to `transport.Session` + WebRTC connection state wired to reset peer slot on failure
- `transport.PairRoomName(a, b)` exported (mirrors PWA's `pairRoomName`) — deterministic room from sorted peer IDs
- `cli/daemon.toml.example` committed; `~/.flit/daemon.toml` stays local