rechrome 1.44.0 → 1.46.0

package/README.md

@@ -151,10 +151,12 @@ comment for some .env loaders. rech quotes it when it saves one.
 
 ### 4. Share with another machine
 
-On the host (the machine with Chrome), make an invite:
+On the host (the machine with Chrome), make an invite. `rech share` has no default transport:
+in a terminal, `rech share` asks which profile and which listeners to share over; in a script,
+name them:
 
 ```bash
-rech share new you@example.com --name alice
+rech share you@example.com --webrtc --name alice
 # Share "alice": you@example.com
 # Invite for one device (unused, it expires …; secret: send it privately):
 #   https://rechrome.pages.dev/#rech1_7fQxC9tZp2mVb8wLrN4hdK3kT9aQ
@@ -168,8 +170,7 @@ rech connect 'https://rechrome.pages.dev/#rech1_…'
 rech open https://example.com
 ```
 
-By default the two machines meet over **WebRTC**: neither needs an open port, a VPN or a
-domain. A small signal server introduces them, and then traffic flows peer to peer, end-to-end
+Over **WebRTC** the two machines need no open port, VPN or domain. A small signal server introduces them, and then traffic flows peer to peer, end-to-end
 encrypted with keys the signal server never sees. The first `rech` command after connecting starts
 a small local bridge that keeps the connection open between commands.
 
@@ -180,10 +181,12 @@ expire after 24 hours, and WebRTC shares after 30 days unless renewed.
 
 | On the host | |
 |---|---|
-| `rech share new <profile..> [--name n]` | Invite link (`--via webrtc` by default) |
-| `--via lan` · `--via tailscale` · `--via <IP or listener>` | Direct HTTP instead of (or as well as) WebRTC |
+| `rech share [<profile..>] [--name n]` | Invite link; in a terminal, with no transport flag, pick profile and listeners from a list |
+| `--webrtc` · `--webrtc=<signal-url>` | WebRTC via the built-in `webrtc-default` listener (rechrome.pages.dev: best effort, for trying it out; no speed or uptime promise) · via your own signal server (its listener is made if needed) |
+| `--lan` · `--tailscale` · `--via <listener,…>` | Direct HTTP on this network · your tailnet · existing listeners (`rech listener ls`); combine several for one link each |
 | `--devices 3` · `--approve` | Let 3 devices redeem it · make each new device wait for `rech share approve` |
-| `--expires 7d` · `--invite-ttl 1h` · `--signal <url>` | Lifetimes · your [own signal server](docs/signal-selfhost.md) |
+| `--expires 7d` · `--invite-ttl 1h` | Lifetimes |
+| `rech listener add <name> --webrtc=<signal-url> [--turn <url>]… [--turn-env VAR]…` | A WebRTC listener on your [own signal server](docs/signal-selfhost.md), with optional STUN/TURN |
 | `rech share ls` · `rech share devices <share> [--rm <device>]` | Shares, devices, expiry · drop one device |
 | `rech share allow\|deny <share> <profile..>` | Change the profiles; the link and devices stay |
 | `rech share rotate <share>` | A fresh invite; the old one stops working |
@@ -201,9 +204,12 @@ navigation, tabs, snapshots, screenshots and basic interactions, but not `eval`/
 filesystem commands (see [Remote access](#remote-access)).
 
 **WebRTC needs** `node-datachannel`, installed on first use into `~/.rechrome/webrtc`. When a
-direct path can't be found (some corporate networks, symmetric NAT), give the host TURN: set
-`CF_TURN_KEY_ID` and `CF_TURN_API_TOKEN` (a [Cloudflare TURN](https://developers.cloudflare.com/realtime/turn/)
-key; its free tier is 1,000 GB/month) in the daemon's environment, or share `--via tailscale`.
+direct path can't be found (some corporate networks, symmetric NAT), give the host TURN: add it to
+a WebRTC listener as one URL, `rech listener add home --webrtc=https://signal.example.com/ --turn-env TEAM_TURN`
+with `TEAM_TURN=turns://user:pass@turn.example.com:5349` (user and password percent-encoded;
+`rech listener ls` shows the username, never the password). Or set `CF_TURN_KEY_ID` and
+`CF_TURN_API_TOKEN` (a [Cloudflare TURN](https://developers.cloudflare.com/realtime/turn/) key; its
+free tier is 1,000 GB/month) in the daemon's environment, or share `--tailscale`.
 
 **Keep links out of git.** `rech status`, `rech connect` and `rech share --save` warn when the file
 holding `RECHROME_URL` is committed, staged, not git-ignored, or readable by other users. Links
@@ -398,6 +404,23 @@ cp .env.example .env.local
 >
 > Shell-set `PLAYWRIGHT_MCP_*` variables take priority over `.env.local`, so you can always override per-command without editing files.
 
+### Downloading files
+
+A file the page downloads (a link, an export button) goes to **your** machine. Any type
+works. It lands in `<project>/.rechrome/output/` with the command's other files. The host
+saves it in a private folder, hands it to the client once, and then deletes it. A download
+that is never fetched is deleted after 10 minutes. Each download is logged on the host
+with its name, size and sha256.
+
+Keeping a copy on the host is opt-in, per listener:
+
+```bash
+rech listener set <listener> --keep-downloads    # --no-keep-downloads: back to client-only
+```
+
+A download that finishes after its command has returned is reported, and handed over,
+by the next command on that tab.
+
 ### Uploading files
 
 `rech upload <file>` puts a local image into the page: a file picker, an

package/listeners.js

@@ -21,11 +21,123 @@ Types: ${UPLOAD_TYPES.join(", ")}, up to ${MAX_UPLOAD_BYTES / 1024 / 1024} MiB.
 // listeners.ts
 import { isIP } from "net";
 import { createHash, randomBytes } from "crypto";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+
+// shares.ts
 import { homedir } from "os";
 import { join as join2 } from "path";
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
+
+// secret.ts
+var B58 = "[1-9A-HJ-NP-Za-km-z]";
+var BODY_LEN = 22;
+var SUM_LEN = 6;
+var TOKEN_PATTERN = new RegExp(`\\brech1_${B58}{${BODY_LEN + SUM_LEN}}\\b`, "g");
+var EXACT = new RegExp(`^rech1_(${B58}{${BODY_LEN}})(${B58}{${SUM_LEN}})$`);
+var CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let i = 0;i < 256; i++) {
+    let c = i;
+    for (let k = 0;k < 8; k++)
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    t[i] = c >>> 0;
+  }
+  return t;
+})();
+
+// shares.ts
+var DEFAULT_SIGNAL = "https://rechrome.pages.dev/";
+var DEFAULT_RTC = "webrtc-default";
+var SHARES_FILE = join2(homedir(), ".rechrome", "shares.json");
+function normalizeSignal(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Signal server must be an http(s) URL, e.g. https://signal.example.com; got "${value}"`);
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+    throw new Error("Signal server must be a plain http(s) URL, without credentials, query or fragment");
+  if (!url.pathname.endsWith("/"))
+    url.pathname += "/";
+  return url.toString();
+}
+var bearerCache = new Map;
+
+// listeners.ts
+var LEGACY_RTC = "webrtc";
+var DEFAULT_RTC_NOTE = "best effort, for trying it out: no speed or uptime promise. Host your own: rech listener add <name> --webrtc=<url>";
+var defaultRtcListener = () => ({ name: DEFAULT_RTC, kind: "webrtc", signal: DEFAULT_SIGNAL, builtin: true });
+function rtcListeners(config) {
+  return [...config?.rtcListeners ?? [], defaultRtcListener()];
+}
+function shareRtcListeners(share, config) {
+  const all = rtcListeners(config);
+  const out = [];
+  for (const via of share.via) {
+    if (via === LEGACY_RTC)
+      out.push({ name: LEGACY_RTC, kind: "webrtc", signal: normalizeSignal(share.signal ?? DEFAULT_SIGNAL), builtin: true });
+    else {
+      const l = all.find((x) => x.name === via);
+      if (l)
+        out.push(l);
+    }
+  }
+  return out;
+}
+function parseIceUrl(value) {
+  const raw = value.trim();
+  const m = /^(stuns?|turns?):(?:\/\/)?(?:([^:@/\s]*)(?::([^@/\s]*))?@)?([^/?#@\s]+)(\?[^#]*)?$/i.exec(raw);
+  if (!m)
+    throw new Error("A STUN/TURN server is a URL like turns://user:pass@turn.example.com:5349 or stun:stun.example.com:3478");
+  const [, scheme, user, pass, hostPort, query = ""] = m;
+  const kind = scheme.toLowerCase();
+  if (query && !/^\?transport=(udp|tcp)$/i.test(query))
+    throw new Error("A STUN/TURN URL may only carry ?transport=udp or ?transport=tcp");
+  const urls = `${kind}:${hostPort}${query}`;
+  if (user === undefined)
+    return { urls };
+  if (kind.startsWith("stun"))
+    throw new Error("A STUN server takes no username or password");
+  let username, credential;
+  try {
+    username = decodeURIComponent(user);
+    credential = decodeURIComponent(pass ?? "");
+  } catch {
+    throw new Error("The TURN username or password has a bad %-escape");
+  }
+  if (!username || !credential)
+    throw new Error("A TURN URL with credentials needs both: turns://user:pass@host:port");
+  return { urls, username, credential };
+}
+function iceLabel(s) {
+  const url = [s.urls].flat()[0] ?? "";
+  if (!s.username)
+    return url;
+  const [scheme, ...rest] = url.split(":");
+  return `${scheme}://${encodeURIComponent(s.username)}:\u2026@${rest.join(":")}`;
+}
+function validateRtcListeners(value, socketNames) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error("listeners.json rtcListeners must be a list");
+  const names = new Set;
+  for (const l of value) {
+    if (!l || l.kind !== "webrtc" || typeof l.name !== "string" || !/^[a-zA-Z0-9_-]{1,40}$/.test(l.name) || typeof l.signal !== "string")
+      throw new Error("Each WebRTC listener needs a name and a signal server URL");
+    if (l.name === DEFAULT_RTC || l.name === LEGACY_RTC || names.has(l.name) || socketNames.has(l.name))
+      throw new Error(`Listener names must be unique ("${DEFAULT_RTC}" and "${LEGACY_RTC}" are built in)`);
+    l.signal = normalizeSignal(l.signal);
+    if (l.ice !== undefined && (!Array.isArray(l.ice) || l.ice.some((s) => !s || typeof s.urls !== "string" && !Array.isArray(s.urls) || s.username !== undefined && typeof s.username !== "string" || s.credential !== undefined && typeof s.credential !== "string")))
+      throw new Error(`WebRTC listener "${l.name}": ice must be a list of {urls, username?, credential?}`);
+    delete l.builtin;
+    names.add(l.name);
+  }
+}
 var MAX_RETIRED_PORTS = 32;
-var LISTENERS_FILE = join2(homedir(), ".rechrome", "listeners.json");
+var LISTENERS_FILE = join3(homedir2(), ".rechrome", "listeners.json");
 var isLoopback = (host) => host === "::1" || /^127\./.test(host);
 var listenerAddress = (l) => `${l.host.includes(":") ? `[${l.host}]` : l.host}:${l.port}`;
 var profileOutputPrefix = (profile) => `profiles/${createHash("sha256").update(profile).digest("hex")}/`;
@@ -80,6 +192,8 @@ function validateListeners(value) {
       throw new Error("readSecrets must be true or false");
     if (l.readCookies !== undefined && typeof l.readCookies !== "boolean")
       throw new Error("readCookies must be true or false");
+    if (l.keepDownloads !== undefined && typeof l.keepDownloads !== "boolean")
+      throw new Error("keepDownloads must be true or false");
     const address = listenerAddress(l);
     if (names.has(l.name) || addresses.has(address) || keys.has(l.key))
       throw new Error("Listener names, addresses, and credentials must be unique");
@@ -87,6 +201,7 @@ function validateListeners(value) {
     addresses.add(address);
     keys.add(l.key);
   }
+  validateRtcListeners(config.rtcListeners, names);
   if (config.retiredPorts !== undefined && (!Array.isArray(config.retiredPorts) || config.retiredPorts.some((p) => !Number.isInteger(p) || p < 1 || p > 65535)))
     throw new Error("listeners.json retiredPorts must be a list of ports");
   return config;
@@ -116,7 +231,7 @@ async function writeListeners(config) {
     config.retiredPorts = retired;
   else
     delete config.retiredPorts;
-  await mkdir(join2(homedir(), ".rechrome"), { recursive: true });
+  await mkdir(join3(homedir2(), ".rechrome"), { recursive: true });
   const temp = `${LISTENERS_FILE}.${randomBytes(6).toString("hex")}.tmp`;
   await writeFile(temp, JSON.stringify(config, null, 2) + `
 `, { mode: 384 });
@@ -241,24 +356,32 @@ function planProfileRemoval(key, registry, listeners, managedRoot) {
   return { keys, listeners: edits, ...managed ? { dataDir: entry.userDataDir } : {} };
 }
 export {
+  DEFAULT_RTC,
+  DEFAULT_RTC_NOTE,
+  LEGACY_RTC,
   LISTENERS_FILE,
   allowProfiles,
   authorizeProfileRequest,
   canReadProfileFile,
   canonicalProfileKeys,
+  defaultRtcListener,
   denyProfiles,
+  iceLabel,
   isLoopback,
   listenerAddress,
   normalizePrefix,
   normalizePublicUrl,
+  parseIceUrl,
   planProfileRemoval,
   profileOutputPrefix,
   readListeners,
   resolveAllowedProfile,
   retirePorts,
   rotateListenerKey,
+  rtcListeners,
   serviceUrl,
   setPublicUrl,
+  shareRtcListeners,
   validateListeners,
   writeListeners
 };

package/listeners.ts

@@ -4,12 +4,89 @@ import { createHash, randomBytes } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { DEFAULT_RTC, DEFAULT_SIGNAL, normalizeSignal } from "./shares.ts";
 
 // publicUrl: where a reverse proxy (Tailscale Serve, Caddy, nginx, ...) exposes this listener.
-export type Listener = { name: string; host: string; port: number; key: string; profiles: string[] | "*"; prefix?: string; publicUrl?: string; uploads?: UploadPolicy | false; readSecrets?: boolean; readCookies?: boolean };
+export type Listener = { name: string; host: string; port: number; key: string; profiles: string[] | "*"; prefix?: string; publicUrl?: string; uploads?: UploadPolicy | false; readSecrets?: boolean; readCookies?: boolean; keepDownloads?: boolean };
 // retiredPorts: ports of removed listeners, newest last. New listeners skip them so a link
 // saved for a removed listener gets "connection refused", not some other listener's answer.
-export type ListenerConfig = { version: 1; listeners: Listener[]; retiredPorts?: number[] };
+// rtcListeners: WebRTC transports (a signal server, plus optional STUN/TURN). They live under
+// their own key so a daemon from before they existed reads the file unchanged and ignores them.
+export type ListenerConfig = { version: 1; listeners: Listener[]; retiredPorts?: number[]; rtcListeners?: RtcListener[] };
+export type IceServer = { urls: string | string[]; username?: string; credential?: string };
+export type RtcListener = { name: string; kind: "webrtc"; signal: string; ice?: IceServer[]; builtin?: true };
+
+// The built-in WebRTC listener: the public signal server, for trying sharing out. Never written
+// to listeners.json; a share names it in `via`. The legacy `via: ["webrtc"]` (+ share.signal)
+// maps to a virtual listener named "webrtc".
+export { DEFAULT_RTC };
+export const LEGACY_RTC = "webrtc";
+export const DEFAULT_RTC_NOTE = "best effort, for trying it out: no speed or uptime promise. Host your own: rech listener add <name> --webrtc=<url>";
+export const defaultRtcListener = (): RtcListener => ({ name: DEFAULT_RTC, kind: "webrtc", signal: DEFAULT_SIGNAL, builtin: true });
+
+/** Every WebRTC listener a share can name: the saved ones plus the built-in default. */
+export function rtcListeners(config: ListenerConfig | null): RtcListener[] {
+  return [...(config?.rtcListeners ?? []), defaultRtcListener()];
+}
+
+/** The WebRTC listeners a share is offered on, in `via` order. */
+export function shareRtcListeners(share: { via: string[]; signal?: string }, config: ListenerConfig | null): RtcListener[] {
+  const all = rtcListeners(config);
+  const out: RtcListener[] = [];
+  for (const via of share.via) {
+    if (via === LEGACY_RTC) out.push({ name: LEGACY_RTC, kind: "webrtc", signal: normalizeSignal(share.signal ?? DEFAULT_SIGNAL), builtin: true });
+    else { const l = all.find(x => x.name === via); if (l) out.push(l); }
+  }
+  return out;
+}
+
+/**
+ * One STUN/TURN server from a URL: `turn[s]://user:pass@host:port?transport=tcp` (user and
+ * password percent-encoded) becomes {urls: "turn[s]:host:port?transport=tcp", username, credential}.
+ * `stun:host:port` and `turn:host:port` without credentials are accepted as they are.
+ */
+export function parseIceUrl(value: string): IceServer {
+  const raw = value.trim();
+  const m = /^(stuns?|turns?):(?:\/\/)?(?:([^:@/\s]*)(?::([^@/\s]*))?@)?([^/?#@\s]+)(\?[^#]*)?$/i.exec(raw);
+  if (!m) throw new Error("A STUN/TURN server is a URL like turns://user:pass@turn.example.com:5349 or stun:stun.example.com:3478");
+  const [, scheme, user, pass, hostPort, query = ""] = m;
+  const kind = scheme!.toLowerCase();
+  if (query && !/^\?transport=(udp|tcp)$/i.test(query)) throw new Error("A STUN/TURN URL may only carry ?transport=udp or ?transport=tcp");
+  const urls = `${kind}:${hostPort}${query}`;
+  if (user === undefined) return { urls };
+  if (kind.startsWith("stun")) throw new Error("A STUN server takes no username or password");
+  let username: string, credential: string;
+  try { username = decodeURIComponent(user); credential = decodeURIComponent(pass ?? ""); }
+  catch { throw new Error("The TURN username or password has a bad %-escape"); }
+  if (!username || !credential) throw new Error("A TURN URL with credentials needs both: turns://user:pass@host:port");
+  return { urls, username, credential };
+}
+
+/** How a STUN/TURN server is shown: the username, never the password. */
+export function iceLabel(s: IceServer): string {
+  const url = [s.urls].flat()[0] ?? "";
+  if (!s.username) return url;
+  const [scheme, ...rest] = url.split(":");
+  return `${scheme}://${encodeURIComponent(s.username)}:…@${rest.join(":")}`;
+}
+
+function validateRtcListeners(value: unknown, socketNames: Set<string>): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) throw new Error("listeners.json rtcListeners must be a list");
+  const names = new Set<string>();
+  for (const l of value as RtcListener[]) {
+    if (!l || l.kind !== "webrtc" || typeof l.name !== "string" || !/^[a-zA-Z0-9_-]{1,40}$/.test(l.name) || typeof l.signal !== "string")
+      throw new Error("Each WebRTC listener needs a name and a signal server URL");
+    if (l.name === DEFAULT_RTC || l.name === LEGACY_RTC || names.has(l.name) || socketNames.has(l.name))
+      throw new Error(`Listener names must be unique ("${DEFAULT_RTC}" and "${LEGACY_RTC}" are built in)`);
+    l.signal = normalizeSignal(l.signal);
+    if (l.ice !== undefined && (!Array.isArray(l.ice) || l.ice.some(s => !s || (typeof s.urls !== "string" && !Array.isArray(s.urls))
+      || (s.username !== undefined && typeof s.username !== "string") || (s.credential !== undefined && typeof s.credential !== "string"))))
+      throw new Error(`WebRTC listener "${l.name}": ice must be a list of {urls, username?, credential?}`);
+    delete l.builtin;
+    names.add(l.name);
+  }
+}
 const MAX_RETIRED_PORTS = 32;
 export const LISTENERS_FILE = join(homedir(), ".rechrome", "listeners.json");
 export const isLoopback = (host: string) => host === "::1" || /^127\./.test(host);
@@ -63,10 +140,12 @@ export function validateListeners(value: unknown): ListenerConfig {
     if (l.uploads !== undefined && l.uploads !== false) validateUploadPolicy(l.uploads);
     if (l.readSecrets !== undefined && typeof l.readSecrets !== "boolean") throw new Error("readSecrets must be true or false");
     if (l.readCookies !== undefined && typeof l.readCookies !== "boolean") throw new Error("readCookies must be true or false");
+    if (l.keepDownloads !== undefined && typeof l.keepDownloads !== "boolean") throw new Error("keepDownloads must be true or false");
     const address = listenerAddress(l);
     if (names.has(l.name) || addresses.has(address) || keys.has(l.key)) throw new Error("Listener names, addresses, and credentials must be unique");
     names.add(l.name); addresses.add(address); keys.add(l.key);
   }
+  validateRtcListeners(config.rtcListeners, names);
   if (config.retiredPorts !== undefined && (!Array.isArray(config.retiredPorts) || config.retiredPorts.some(p => !Number.isInteger(p) || p < 1 || p > 65535)))
     throw new Error("listeners.json retiredPorts must be a list of ports");
   return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.44.0",
+  "version": "1.46.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"