rechrome 1.36.1 → 1.37.1

package/README.md

@@ -77,9 +77,71 @@ directory outside git. rechrome reads `RECHROME_URL` from the nearest `.rechrome
 When editing a file by hand, quote the URL (`RECHROME_URL="…#key=…"`): unquoted, a `#` starts a
 comment for some .env loaders. rech quotes it when it saves one.
 
-### 4. Use it from another machine
+### 4. Share with another machine
 
-The daemon only listens on this machine until you expose a profile. The recommended way is a
+On the host (the machine with Chrome), make an invite:
+
+```bash
+rech share new you@example.com --name alice
+# Share "alice": you@example.com
+# Invite for one device (unused, it expires …; secret: send it privately):
+#   https://rechrome.pages.dev/#rech1_7fQxC9tZp2mVb8wLrN4hdK3kT9aQ
+#   or in a terminal:  rech connect rech1_7fQxC9tZp2mVb8wLrN4hdK3kT9aQ
+```
+
+On the other machine, inside the project that should use it:
+
+```bash
+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
+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.
+
+**The link is an invite, not a key.** `rech connect` redeems it once: this machine gets its own
+device credential (saved to `.rechrome/.env.local`) and the invite stops working, so a link that
+leaks after it was used is harmless, and if someone else used it first you'll know. Unused invites
+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 |
+| `--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) |
+| `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 |
+| `rech share renew <share> --expires 30d` · `revoke` · `rm` | Extend · cut it off (closes its sessions) · delete |
+
+| On the other machine | |
+|---|---|
+| `rech profile` | The profiles this share gives you |
+| `rech --profile <name> open <url>` | Pick one when the share has several |
+| `rech -s=<name> open <url>` · `rech session ls` · `rech session close <name>` | Separate browser sessions; list and close them |
+| `rech status` | Transport, share, device, expiry |
+
+Each device gets its own browser sessions, apart from every other device and link. A share allows
+navigation, tabs, snapshots, screenshots and basic interactions, but not `eval`/`run-code` or
+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`.
+
+**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
+use a `rech1_` prefix and a checksum, so secret scanners can match them:
+`\brech1_[1-9A-HJ-NP-Za-km-z]{28}\b`.
+
+#### Listener links (reverse proxies)
+
+Before invites, a profile was shared as a listener's link carrying its key (`#key=…`); these
+keep working. The daemon only listens on this machine until you expose a profile. One way is a
 **scoped listener behind a reverse proxy** — shown with Tailscale Serve, but any proxy that
 forwards to `127.0.0.1:<port>` works. The commands are identical in bash, PowerShell and
 `cmd.exe`.
@@ -130,8 +192,10 @@ profile to your LAN address directly (plain HTTP); share the result of `rech sha
 
 ### 5. Manage access
 
+Invite shares are managed with `rech share` (above). Listener links:
+
 ```bash
-rech share ls                                 # everything shared: listener × profile, local and public URLs (keys hidden)
+rech share ls                                 # shares, then listener × profile, local and public URLs (keys hidden)
 rech share you@example.com                    # print one URL again (add --save to use it in this project)
 rech listener allow share teammate@example.com
 rech listener deny share teammate@example.com
@@ -366,6 +430,8 @@ roll up to their parent), or the current directory outside git. So two worktrees
 get separate sessions, and `git checkout` keeps you in the same one. `RECH_IDENTITY=branch`
 restores the older `<remote>/tree/<branch>` keying and `RECH_IDENTITY=cwd` keys on the exact
 directory. Pass `-s=<name>` for a named sub-session, or `--isolate` for a throwaway one.
+A share device's sessions are additionally keyed by its share and device, so they never meet
+another device's or a listener link's; `rech session ls` lists the ones this link drove.
 
 ## Development
 

package/e2e.js

@@ -0,0 +1,164 @@
+// @bun
+// secret.ts
+var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var B58 = "[1-9A-HJ-NP-Za-km-z]";
+var BODY_LEN = 22;
+var SUM_LEN = 6;
+var SECRET_BYTES = 16;
+var TOKEN_PATTERN = new RegExp(`\\brech1_${B58}{${BODY_LEN + SUM_LEN}}\\b`, "g");
+var EXACT = new RegExp(`^rech1_(${B58}{${BODY_LEN}})(${B58}{${SUM_LEN}})$`);
+function unbase58(text, length) {
+  let n = 0n;
+  for (const c of text) {
+    const i = ALPHABET.indexOf(c);
+    if (i < 0)
+      return null;
+    n = n * 58n + BigInt(i);
+  }
+  const out = new Uint8Array(length);
+  for (let i = length - 1;i >= 0; i--) {
+    out[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+  return n === 0n ? out : null;
+}
+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;
+})();
+function crc32(bytes) {
+  let c = 4294967295;
+  for (const b of bytes)
+    c = CRC_TABLE[(c ^ b) & 255] ^ c >>> 8;
+  return (c ^ 4294967295) >>> 0;
+}
+var u32 = (n) => new Uint8Array([n >>> 24, n >>> 16 & 255, n >>> 8 & 255, n & 255]);
+function parseToken(token) {
+  const m = EXACT.exec(token.trim());
+  if (!m)
+    return { ok: false, reason: "format" };
+  const secret = unbase58(m[1], SECRET_BYTES), sum = unbase58(m[2], 4);
+  if (!secret || !sum)
+    return { ok: false, reason: "format" };
+  const expected = u32(crc32(secret));
+  return sum.every((b, i) => b === expected[i]) ? { ok: true, secret } : { ok: false, reason: "checksum" };
+}
+
+// e2e.ts
+var PROTO = "rech-e2e-1";
+var MAX_CHUNK = 12000;
+var CONFIRM_TIMEOUT_MS = 5000;
+var FLAG_CONFIRM = 1;
+var VER = 1;
+var HEADER_LEN = 14;
+var NONCE_LEN = 12;
+var TAG_LEN = 16;
+var COUNTER_MAX = (1n << 64n) - 1n;
+var subtle = globalThis.crypto.subtle;
+var enc = new TextEncoder;
+var dec = new TextDecoder;
+var concat = (...parts) => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+};
+var sha256 = async (bytes) => new Uint8Array(await subtle.digest("SHA-256", bytes));
+function ikmOf(token) {
+  const parsed = parseToken(token);
+  if (!parsed.ok)
+    throw new Error("e2e: invalid share secret");
+  return parsed.secret;
+}
+async function hkdfKey(ikm, salt, info) {
+  const base = await subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+  const bits = await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info: enc.encode(info) }, base, 256);
+  return subtle.importKey("raw", bits, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+async function deriveDirKeys(token, transcriptHash) {
+  const ikm = ikmOf(token);
+  return {
+    h2c: await hkdfKey(ikm, transcriptHash, `rech/${PROTO}/key/host->client`),
+    c2h: await hkdfKey(ikm, transcriptHash, `rech/${PROTO}/key/client->host`)
+  };
+}
+var fingerprints = (sdp) => [...sdp.matchAll(/^a=fingerprint:(.*)$/gim)].map((m) => m[1].trim().toLowerCase()).sort();
+var firstAttr = (sdp, name) => (new RegExp(`^a=${name}:(.*)$`, "im").exec(sdp)?.[1] ?? "").trim().toLowerCase();
+async function transcriptHash(offerSdp, answerSdp) {
+  const offer = fingerprints(offerSdp), answer = fingerprints(answerSdp);
+  if (!offer.length || !answer.length)
+    throw new Error("e2e: missing DTLS fingerprint");
+  if ([...offer, ...answer].some((fp) => !fp.startsWith("sha-256")))
+    throw new Error("e2e: non-sha-256 DTLS fingerprint");
+  return sha256(enc.encode(`${PROTO}
+` + `offer=${offer.join(",")};setup=${firstAttr(offerSdp, "setup")};ufrag=${firstAttr(offerSdp, "ice-ufrag")}
+` + `answer=${answer.join(",")};setup=${firstAttr(answerSdp, "setup")};ufrag=${firstAttr(answerSdp, "ice-ufrag")}`));
+}
+var newSendState = () => ({ ctr: 0n });
+var newRecvState = () => ({ last: -1n });
+function nonceOf(ctr) {
+  const n = new Uint8Array(NONCE_LEN);
+  new DataView(n.buffer).setBigUint64(4, ctr, false);
+  return n;
+}
+async function seal(key, state, flags, th, plaintext) {
+  const ctr = state.ctr;
+  if (ctr >= COUNTER_MAX)
+    throw new Error("e2e: nonce counter overflow");
+  state.ctr = ctr + 1n;
+  const nonce = nonceOf(ctr);
+  const header = new Uint8Array(HEADER_LEN);
+  header[0] = VER;
+  header[1] = flags & 255;
+  header.set(nonce, 2);
+  const sealed = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: concat(header, th), tagLength: 128 }, key, plaintext));
+  return concat(header, sealed).buffer;
+}
+async function open(key, frame, th, state) {
+  const buf = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+  if (buf.length < HEADER_LEN + TAG_LEN)
+    throw new Error("e2e: short frame");
+  if (buf[0] !== VER)
+    throw new Error("e2e: bad version");
+  const header = buf.subarray(0, HEADER_LEN), nonce = buf.subarray(2, HEADER_LEN);
+  const view = new DataView(nonce.buffer, nonce.byteOffset, NONCE_LEN);
+  if (view.getUint32(0, false) !== 0)
+    throw new Error("e2e: bad epoch");
+  const ctr = view.getBigUint64(4, false);
+  const plain = await subtle.decrypt({ name: "AES-GCM", iv: nonce, additionalData: concat(header, th), tagLength: 128 }, key, buf.subarray(HEADER_LEN));
+  if (state.last === -1n && ctr !== 0n)
+    throw new Error("e2e: first frame must be counter-0");
+  if (ctr <= state.last)
+    throw new Error("e2e: replay/reorder");
+  state.last = ctr;
+  return { flags: header[1], plaintext: new Uint8Array(plain) };
+}
+var pack = (obj) => enc.encode(JSON.stringify(obj));
+var unpack = (bytes) => JSON.parse(dec.decode(bytes));
+function randomHex(n) {
+  return Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(n))).toString("hex");
+}
+export {
+  CONFIRM_TIMEOUT_MS,
+  FLAG_CONFIRM,
+  MAX_CHUNK,
+  PROTO,
+  deriveDirKeys,
+  newRecvState,
+  newSendState,
+  open,
+  pack,
+  randomHex,
+  seal,
+  transcriptHash,
+  unpack
+};

package/e2e.ts

@@ -0,0 +1,106 @@
+// End-to-end encryption for the WebRTC DataChannel ("rech-e2e-1"). Ported from agent-yes's
+// lab/ui/e2e.js (MIT, same author) with rech's own labels and rech1_ secrets.
+//
+// Threat model: a fully compromised signal server, or an active MITM on the media path, may
+// drop connections and see metadata, but must not read or inject traffic or learn the secret.
+// The signal server only ever sees roomOf/roomAuthOf (one-way HKDF outputs, see secret.ts).
+// The AES keys are HKDF(secret, transcriptHash) where the transcript binds both DTLS
+// fingerprints: a relay that swaps in its own fingerprints derives different keys, and the
+// mandatory key-confirmation round fails closed.
+import { parseToken } from "./secret.ts";
+
+export const PROTO = "rech-e2e-1";
+export const MAX_CHUNK = 12_000;          // plaintext bytes per sealed frame, well under SCTP limits
+export const CONFIRM_TIMEOUT_MS = 5_000;
+export const FLAG_CONFIRM = 0x01;
+const VER = 0x01, HEADER_LEN = 14, NONCE_LEN = 12, TAG_LEN = 16;
+const COUNTER_MAX = (1n << 64n) - 1n;
+const subtle = globalThis.crypto.subtle;
+const enc = new TextEncoder(), dec = new TextDecoder();
+
+const concat = (...parts: Uint8Array[]) => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+};
+const sha256 = async (bytes: Uint8Array) => new Uint8Array(await subtle.digest("SHA-256", bytes as BufferSource));
+
+function ikmOf(token: string): Uint8Array {
+  const parsed = parseToken(token);
+  if (!parsed.ok) throw new Error("e2e: invalid share secret");
+  return parsed.secret;
+}
+
+async function hkdfKey(ikm: Uint8Array, salt: Uint8Array, info: string): Promise<CryptoKey> {
+  const base = await subtle.importKey("raw", ikm as BufferSource, "HKDF", false, ["deriveBits"]);
+  const bits = await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: salt as BufferSource, info: enc.encode(info) }, base, 256);
+  return subtle.importKey("raw", bits, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+
+/** Directional keys, fresh per connection (the transcript is the salt). Host seals h2c, client c2h. */
+export async function deriveDirKeys(token: string, transcriptHash: Uint8Array): Promise<{ h2c: CryptoKey; c2h: CryptoKey }> {
+  const ikm = ikmOf(token);
+  return {
+    h2c: await hkdfKey(ikm, transcriptHash, `rech/${PROTO}/key/host->client`),
+    c2h: await hkdfKey(ikm, transcriptHash, `rech/${PROTO}/key/client->host`),
+  };
+}
+
+const fingerprints = (sdp: string) => [...sdp.matchAll(/^a=fingerprint:(.*)$/gim)].map(m => m[1].trim().toLowerCase()).sort();
+const firstAttr = (sdp: string, name: string) => (new RegExp(`^a=${name}:(.*)$`, "im").exec(sdp)?.[1] ?? "").trim().toLowerCase();
+
+/** Bind the session to the negotiated DTLS handshake. Both sides compute it from (offer, answer). */
+export async function transcriptHash(offerSdp: string, answerSdp: string): Promise<Uint8Array> {
+  const offer = fingerprints(offerSdp), answer = fingerprints(answerSdp);
+  if (!offer.length || !answer.length) throw new Error("e2e: missing DTLS fingerprint");
+  if ([...offer, ...answer].some(fp => !fp.startsWith("sha-256"))) throw new Error("e2e: non-sha-256 DTLS fingerprint");
+  return sha256(enc.encode(`${PROTO}\n`
+    + `offer=${offer.join(",")};setup=${firstAttr(offerSdp, "setup")};ufrag=${firstAttr(offerSdp, "ice-ufrag")}\n`
+    + `answer=${answer.join(",")};setup=${firstAttr(answerSdp, "setup")};ufrag=${firstAttr(answerSdp, "ice-ufrag")}`));
+}
+
+export type SendState = { ctr: bigint };
+export type RecvState = { last: bigint };
+export const newSendState = (): SendState => ({ ctr: 0n });
+export const newRecvState = (): RecvState => ({ last: -1n });
+
+function nonceOf(ctr: bigint): Uint8Array {
+  const n = new Uint8Array(NONCE_LEN);
+  new DataView(n.buffer).setBigUint64(4, ctr, false);
+  return n;
+}
+
+/** Wire frame: VER | FLAGS | NONCE(12) | CIPHERTEXT+TAG; AAD = header | transcriptHash. */
+export async function seal(key: CryptoKey, state: SendState, flags: number, th: Uint8Array, plaintext: Uint8Array): Promise<ArrayBuffer> {
+  const ctr = state.ctr;
+  if (ctr >= COUNTER_MAX) throw new Error("e2e: nonce counter overflow");
+  state.ctr = ctr + 1n; // claimed before the await: concurrent seals never share a nonce
+  const nonce = nonceOf(ctr);
+  const header = new Uint8Array(HEADER_LEN);
+  header[0] = VER; header[1] = flags & 0xff; header.set(nonce, 2);
+  const sealed = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: nonce as BufferSource, additionalData: concat(header, th) as BufferSource, tagLength: 128 }, key, plaintext as BufferSource));
+  return concat(header, sealed).buffer as ArrayBuffer;
+}
+
+/** Throws on any tampering, replay or reordering; the caller must then close the channel. */
+export async function open(key: CryptoKey, frame: ArrayBuffer | Uint8Array, th: Uint8Array, state: RecvState): Promise<{ flags: number; plaintext: Uint8Array }> {
+  const buf = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+  if (buf.length < HEADER_LEN + TAG_LEN) throw new Error("e2e: short frame");
+  if (buf[0] !== VER) throw new Error("e2e: bad version");
+  const header = buf.subarray(0, HEADER_LEN), nonce = buf.subarray(2, HEADER_LEN);
+  const view = new DataView(nonce.buffer, nonce.byteOffset, NONCE_LEN);
+  if (view.getUint32(0, false) !== 0) throw new Error("e2e: bad epoch");
+  const ctr = view.getBigUint64(4, false);
+  const plain = await subtle.decrypt({ name: "AES-GCM", iv: nonce as BufferSource, additionalData: concat(header, th) as BufferSource, tagLength: 128 }, key, buf.subarray(HEADER_LEN) as BufferSource);
+  if (state.last === -1n && ctr !== 0n) throw new Error("e2e: first frame must be counter-0");
+  if (ctr <= state.last) throw new Error("e2e: replay/reorder");
+  state.last = ctr;
+  return { flags: header[1], plaintext: new Uint8Array(plain) };
+}
+
+export const pack = (obj: unknown) => enc.encode(JSON.stringify(obj));
+export const unpack = (bytes: Uint8Array) => JSON.parse(dec.decode(bytes));
+export function randomHex(n: number): string {
+  return Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(n))).toString("hex");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.36.1",
+  "version": "1.37.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"
@@ -27,7 +27,17 @@
     "serve.ts",
     "vendor",
     "scoped-upload.ts",
-    "scoped-upload.js"
+    "scoped-upload.js",
+    "secret.ts",
+    "secret.js",
+    "shares.ts",
+    "shares.js",
+    "e2e.ts",
+    "e2e.js",
+    "webrtc.ts",
+    "webrtc.js",
+    "signal-relay.ts",
+    "signal-relay.js"
   ],
   "type": "module",
   "scripts": {
@@ -36,11 +46,12 @@
     "vendor-cli": "bash scripts/vendor-cli.sh",
     "prepare": "bash scripts/vendor-cli.sh --prepare",
     "check-pack": "bash scripts/check-pack.sh",
-    "prepublishOnly": "bash scripts/vendor-cli.sh && sed 's/\\.ts/\\.js/g' rechrome.ts > rechrome.js && sed 's/\\.ts/\\.js/g' serve.ts > serve.js && bun build extension-token.ts --target=bun --outfile=extension-token.js && bun build daemon-manager.ts --target=bun --outfile=daemon-manager.js && bun build listeners.ts --target=bun --outfile=listeners.js && bun build scoped-upload.ts --target=bun --outfile=scoped-upload.js && bash scripts/check-pack.sh"
+    "prepublishOnly": "bash scripts/vendor-cli.sh && sed 's/\\.ts/\\.js/g' rechrome.ts > rechrome.js && sed 's/\\.ts/\\.js/g' serve.ts > serve.js && bun build extension-token.ts --target=bun --outfile=extension-token.js && bun build daemon-manager.ts --target=bun --outfile=daemon-manager.js && bun build listeners.ts --target=bun --outfile=listeners.js && bun build scoped-upload.ts --target=bun --outfile=scoped-upload.js && bun build secret.ts --target=bun --external node-datachannel --outfile=secret.js && bun build shares.ts --target=bun --external node-datachannel --outfile=shares.js && bun build e2e.ts --target=bun --external node-datachannel --outfile=e2e.js && bun build webrtc.ts --target=bun --external node-datachannel --outfile=webrtc.js && bun build signal-relay.ts --target=bun --external node-datachannel --outfile=signal-relay.js && bash scripts/check-pack.sh"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/yargs": "^17.0.35"
+    "@types/yargs": "^17.0.35",
+    "node-datachannel": "^0.32.3"
   },
   "release": {
     "branches": [
@@ -49,5 +60,8 @@
   },
   "dependencies": {
     "yargs": "^18.2.0"
-  }
+  },
+  "trustedDependencies": [
+    "node-datachannel"
+  ]
 }