rechrome 1.36.0 → 1.37.0

package/serve.js

@@ -1,7 +1,10 @@
 import { receiveUpload, readRequestJson } from "./scoped-upload.js";
 import { readListeners, listenerAddress, authorizeProfileRequest, canReadProfileFile, profileOutputPrefix, normalizePrefix, resolveAllowedProfile, type Listener } from "./listeners.js";
+import { WEBRTC, authorizeCredential, credentialForBearer, readShares, redeemInvite, shareProblem, updateShares, webrtcCredentials, type Credential, type ShareConfig } from "./shares.js";
+import { bearerOf, safeEqual } from "./secret.js";
+import { WebrtcHost } from "./webrtc.js";
 import { file } from "bun";
-import { createHash, X509Certificate } from "crypto";
+import { createHash, randomBytes, X509Certificate } from "crypto";
 import { mkdirSync, lstatSync, chmodSync, unlinkSync, accessSync, readdirSync, realpathSync, constants as fsConstants } from "fs";
 import { join, resolve, relative, isAbsolute } from "path";
 import { tmpdir } from "os";
@@ -19,6 +22,7 @@ import {
   readTokenRegistry,
   readChromeProfileCache,
   checkTailscaleServe,
+  chromeDataAccessHint,
 } from "./rechrome.js";
 
 const TAILSCALE_BIN = process.env.TAILSCALE_BIN || "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
@@ -122,6 +126,16 @@ export function provesRelayAlive(o: { stdout: string; stderr: string }): boolean
   return true;
 }
 
+/**
+ * The relay checks Chrome's data folder for the installed extension before connecting. Under
+ * macOS TCC that read fails and it reports "Playwright Extension not found" although the
+ * extension is installed — name the real cause instead of sending the user to reinstall.
+ */
+export function explainExtensionNotFound(output: string, accessProblem: string | undefined): string | undefined {
+  if (!accessProblem || !/Playwright Extension not found in/i.test(output)) return undefined;
+  return `[rech] the extension is probably installed; this daemon ${accessProblem}\n`;
+}
+
 export function inferSilentExtensionFailure(options: {
   status: number;
   stdout: string;
@@ -256,24 +270,63 @@ export function splitCommand(cmd: string): string[] {
     t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t);
 }
 
-async function resolveProfileDirectory(nameOrEmail: string): Promise<string> {
+/** Why this daemon cannot read Chrome's data folder; reported by /ping so `rech status` shows it. */
+let chromeAccessProblem: string | undefined;
+/** Log (once) why Chrome's data folder is unreadable — under launchd/oxmgr on macOS this is TCC. */
+export function warnChromeDataAccess(path: string, error: unknown): void {
+  if (chromeAccessProblem) return;
+  const message = error instanceof Error ? error.message : String(error);
+  chromeAccessProblem = `cannot read ${path} (${message}). ${chromeDataAccessHint(error) ?? "Profile names and emails cannot be resolved here."}`;
+  log(chromeAccessProblem);
+}
+
+/** A profile name or email could not be mapped to its Chrome folder because Local State is unreadable. */
+export class ProfileResolutionError extends Error {
+  constructor(readonly profile: string, statePath: string, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const hint = chromeDataAccessHint(cause);
+    super(`[rech] cannot find the Chrome folder for profile "${profile}": ${statePath} is unreadable (${message}). Refusing, so Chrome does not create a new empty profile named "${profile}".\n`
+      + `  Register it once (records its folder in ~/.rechrome): rech setup --profile ${JSON.stringify(profile)}\n`
+      + `  Or select the folder directly, e.g. rech --profile "Profile 1" …\n`
+      + (hint ? `  ${hint}\n` : ""));
+    this.name = "ProfileResolutionError";
+  }
+}
+
+export async function resolveProfileDirectory(
+  nameOrEmail: string,
+  registry?: Record<string, { profileDir?: string }>,
+  statePaths: string[] = [
+    join(HOME || "~", "Library/Application Support/Google/Chrome/Local State"),
+    join(HOME || "~", ".config/google-chrome/Local State"),
+    join(HOME || "~", "AppData/Local/Google/Chrome/User Data/Local State"),
+  ],
+): Promise<string> {
   if (/^(Default|Profile \d+)$/i.test(nameOrEmail)) return nameOrEmail;
-  const home = HOME || "~";
-  const candidates = [
-    join(home, "Library/Application Support/Google/Chrome/Local State"),
-    join(home, ".config/google-chrome/Local State"),
-    join(home, "AppData/Local/Google/Chrome/User Data/Local State"),
-  ];
-  for (const statePath of candidates) {
-    const f = file(statePath);
-    if (!(await f.exists())) continue;
-    const data = JSON.parse(await f.text());
-    const cache: Record<string, any> = data?.profile?.info_cache ?? {};
-    for (const [dir, info] of Object.entries(cache)) {
-      if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
-        return dir;
+  // setup recorded each registered profile's folder in ~/.rechrome, which macOS privacy (TCC)
+  // never guards, so a launchd/oxmgr daemon resolves it without touching Chrome's data folder.
+  const entry = (registry ?? await readTokenRegistry().catch(() => ({})) as Record<string, { profileDir?: string }>)[nameOrEmail];
+  if (entry?.profileDir) return entry.profileDir;
+  let unreadable: { path: string; error: unknown } | undefined;
+  for (const statePath of statePaths) {
+    try {
+      // Read without an exists() probe: under TCC the stat fails too, and exists() would report
+      // "missing" and hide the denial.
+      const data = JSON.parse(await file(statePath).text());
+      const cache: Record<string, any> = data?.profile?.info_cache ?? {};
+      for (const [dir, info] of Object.entries(cache)) {
+        if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
+          return dir;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") continue;
+      warnChromeDataAccess(statePath, error);
+      unreadable ??= { path: statePath, error };
     }
   }
+  // Passing an email or display name through would make Chrome create a NEW empty profile folder
+  // literally named after it (--profile-directory=me@example.com) instead of opening the real one.
+  if (unreadable) throw new ProfileResolutionError(nameOrEmail, unreadable.path, unreadable.error);
   return nameOrEmail;
 }
 
@@ -397,15 +450,34 @@ async function freeStalePort(port: number, host: string): Promise<void> {
 // the leak self-heals. /ping is deliberately NOT activity (the tray polls it every 2s
 // and would otherwise keep an orphan alive forever).
 const ORPHAN_POLL_INTERVAL_MS = 15_000;
-const ORPHAN_IDLE_EXIT_MS = Number(process.env.RECH_SERVE_IDLE_TIMEOUT_MS) || 5 * 60_000;
+const ORPHAN_IDLE_EXIT_MS = parseIdleTimeout(process.env.RECH_SERVE_IDLE_TIMEOUT_MS);
+
+// `RECH_SERVE_IDLE_TIMEOUT_MS=0` must disable self-exit; `Number(v) || default` turned 0 back into 5 min.
+export function parseIdleTimeout(raw: string | undefined, fallback = 5 * 60_000): number {
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+// A supervisor owns this serve's lifetime, so it is never a leaked foreground serve:
+// RECH_SERVE_MANAGED=1 (set by `rech setup`'s oxmgr/pm2 install), or a LaunchAgent — launchd
+// starts it with ppid 1 and its job label in XPC_SERVICE_NAME. ppid 1 alone is not enough:
+// `setsid rech serve` or `(rech serve &)` also starts with ppid 1 and must still self-exit.
+// Terminal apps set XPC_SERVICE_NAME to "0" or "application.<bundle id>…".
+export function isManagedServe(startPpid: number, env: Record<string, string | undefined> = process.env): boolean {
+  if (env.RECH_SERVE_MANAGED === "1") return true;
+  const label = env.XPC_SERVICE_NAME;
+  return startPpid === 1 && !!label && label !== "0" && !label.startsWith("application.");
+}
 
 // Pure decision predicate (testable). idleTimeoutMs <= 0 disables orphan self-exit.
 export function shouldExitOrphanedServe(opts: {
   orphaned: boolean;
   idleMs: number;
   idleTimeoutMs: number;
+  managed?: boolean;
 }): boolean {
-  return opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
+  return !opts.managed && opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
 }
 
 export const LANDING_HEADERS = {
@@ -449,7 +521,7 @@ a { color: var(--accent); }
 <p>Someone shared a Chrome profile with you through <a href="https://github.com/snomiao/rechrome">rechrome</a>.
 On your computer, inside the project folder that should use it, run these two lines
 (the same in macOS/Linux terminals, PowerShell and cmd):</p>
-<p id="nokey" class="warn" hidden>This link is missing its key (the part after #key=). Ask for the full link from <code>rech share</code>.</p>
+<p id="nokey" class="warn" hidden>This link is missing its key (the part after # — #key=… or #rech1_…). Ask for the full link from <code>rech share</code>.</p>
 <div id="cmds"></div>
 <div id="profiles" hidden><p>Profiles this link can use (pick one to make it the default in the command above):</p><div id="plist"></div></div>
 <p class="small">Needs <a href="https://bun.sh">Bun</a>. Then try <code>rechrome open https://example.com</code>.
@@ -459,13 +531,14 @@ This link contains a secret key: anyone with it can use this browser profile, so
 (() => {
   let url = location.href;
   const key = (location.hash.match(/[#&]key=([^&]*)/) || [])[1];
-  if (!/[#&?]key=/.test(location.hash)) document.getElementById("nokey").hidden = false;
+  const invite = /^#rech1_[1-9A-HJ-NP-Za-km-z]{28}$/.test(location.hash);
+  if (!/[#&?]key=/.test(location.hash) && !invite) document.getElementById("nokey").hidden = false;
   // One command for every shell: two lines (no && vs ; split), one double-quoted URL. Characters a
   // shell expands inside double quotes ($ \` " \\ !) are percent-encoded, which the URL reads the same;
   // %40 goes back to a readable @ (valid in a query, and one less % for cmd to try to expand).
   const quote = s => '"' + s.replace(/%40/g, "@").replace(/[$\`"\\\\!]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase()) + '"';
   const build = u => "bun i -g rechrome\\nrechrome connect " + quote(u);
-  const mask = s => s.replace(/(key=)[^&"\\n]+/, "$1…");
+  const mask = s => s.replace(/(key=)[^&"\\n]+/, "$1…").replace(/(#rech1_[1-9A-HJ-NP-Za-km-z]{4})[1-9A-HJ-NP-Za-km-z]+/, "$1…");
   const root = document.getElementById("cmds");
   const row = document.createElement("div"); row.className = "row";
   const line = document.createElement("div"); line.className = "cmd";
@@ -533,14 +606,24 @@ export async function serve() {
   let orphaned = false;
   let idleSince = Date.now();
   const markActivity = () => { idleSince = Date.now(); };
+  const managed = isManagedServe(process.ppid);
+  if (managed) log("serve is supervised (launchd, a process manager, or RECH_SERVE_MANAGED=1) — idle self-exit disabled");
   setInterval(() => {
     if (process.ppid === 1) orphaned = true;
-    if (shouldExitOrphanedServe({ orphaned, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
+    if (shouldExitOrphanedServe({ orphaned, managed, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
       log(`orphaned foreground serve idle ${Math.round((Date.now() - idleSince) / 1000)}s — exiting (spawning agent is gone)`);
       process.exit(0);
     }
   }, ORPHAN_POLL_INTERVAL_MS);
 
+  // Say at startup, not on the first failed open, when macOS privacy blocks Chrome's data folder.
+  if (process.platform === "darwin") {
+    const chromeDir = join(HOME, "Library/Application Support/Google/Chrome");
+    try { readdirSync(chromeDir); } catch (error) {
+      if ((error as { code?: string }).code !== "ENOENT") warnChromeDataAccess(chromeDir, error);
+    }
+  }
+
   // Reap idle --isolate sessions so single-shot OAuth/login drives don't leak browser contexts.
   adoptOrphanedIsoSessions();
   setInterval(() => {
@@ -564,24 +647,23 @@ export async function serve() {
   const legacy: Listener = { name: "legacy", host: listenHost, port, key, profiles: "*" };
   const policies = new Map<string, Listener>();
   const servers = new Map<string, ReturnType<typeof Bun.serve>>();
-  const startServer = (initial: Listener, reusePort = false) => Bun.serve({
-    hostname: initial.host,
-    port: initial.port,
-    // reusePort is used only as a last-resort fallback (see bindAtStartup below): if an orphaned
-    // holder can't be killed, binding with SO_REUSEADDR keeps serve up (degraded, port-shared)
-    // instead of crash-looping on EADDRINUSE. The normal path binds a clean, exclusive socket.
-    reusePort,
-    tls,
-    error(err) {
-      log(`unhandled error: ${err.message}`);
-      return Response.json({ status: 1, stdout: "", stderr: err.message }, { status: 500 });
-    },
-    async fetch(req, server) {
-      const listener = policies.get(listenerAddress(initial));
-      if (!listener) return new Response("Listener removed", { status: 403 });
-      const key = listener.key;
-      const listenHost = listener.host;
-      const scoped = listener.profiles !== "*";
+  // Shares (shares.json) are reloaded with the listeners below. sessionOwners remembers which
+  // credential drove each session, for `rech session ls` and for closing a revoked share's sessions.
+  let shares: ShareConfig = { version: 1, shares: [] };
+  const sessionOwners = new Map<string, { owner: string; label: string; profile?: string; name: string; lastUsed: number }>();
+  const deviceSeen = new Map<string, number>();
+  const noteDeviceUse = (cred: Credential & { kind: "device" }) => {
+    const now = Date.now();
+    if (now - (deviceSeen.get(cred.device.id) ?? cred.device.lastSeen ?? 0) < 10 * 60_000) return;
+    deviceSeen.set(cred.device.id, now);
+    void updateShares(config => {
+      const device = config.shares.find(s => s.id === cred.share.id)?.devices.find(d => d.id === cred.device.id);
+      if (device) device.lastSeen = now;
+    }).catch(error => log(`could not record device use: ${error}`));
+  };
+
+  const handle = async (req: Request, initialListener: Listener, remoteAddr: () => string): Promise<Response> => {
+      let listener = initialListener;
       const reqUrl = new URL(req.url);
       const prefix = normalizePrefix(listener.prefix);
       // Accept the path with or without the prefix, so a proxy works whether it keeps the
@@ -592,18 +674,70 @@ export async function serve() {
         else if (reqUrl.pathname.startsWith(prefix)) reqUrl.pathname = "/" + reqUrl.pathname.slice(prefix.length);
       }
 
+      // Who is asking: the listener's own key (legacy links, the local management key), or a
+      // share credential (an invite or a device, see shares.js) offered on this transport. A
+      // share narrows the listener to the share's own profiles.
+      const presented = req.headers.get("authorization")?.replace(/^Bearer /, "") ?? "";
+      const cred = presented && !safeEqual(presented, listener.key) ? credentialForBearer(shares, presented) : null;
+      if (cred) {
+        const route = reqUrl.pathname === "/ping" ? "ping" : reqUrl.pathname === "/redeem" ? "redeem" : "use";
+        const denial = authorizeCredential(cred, listener.name, route);
+        if (denial) return Response.json({ status: 1, stdout: "", stderr: `[rech] ${denial.message}\n`, error: denial.message, pending: denial.pending }, { status: denial.status });
+        if (cred.kind === "device") noteDeviceUse(cred);
+        listener = { ...listener, key: presented, profiles: cred.share.profiles };
+      }
+      const key = listener.key;
+      const listenHost = listener.host;
+      const scoped = listener.profiles !== "*";
+      const owner = cred?.kind === "device" ? `share:${cred.share.id}:${cred.device.id}` : `listener:${listener.name}`;
+
+      if (reqUrl.pathname === "/redeem" && req.method === "POST") {
+        if (cred?.kind !== "invite") return Response.json({ error: "Only an invite link can be redeemed." }, { status: 400 });
+        const { name } = await req.json().catch(() => ({})) as { name?: string };
+        try {
+          const device = await updateShares(config => redeemInvite(config, cred.share.id, String(name ?? "")));
+          shares = await readShares();
+          log(`share ${cred.share.label}: invite redeemed by device ${device.id} (${device.name})${device.approved ? "" : ", waiting for approval"}`);
+          return Response.json({ token: device.token, device: { id: device.id, name: device.name, approved: device.approved }, share: cred.share.label, profiles: cred.share.profiles });
+        } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 403 }); }
+      }
+
+      if (reqUrl.pathname === "/profiles") {
+        const denied = authCheck(req, key);
+        if (denied) return denied;
+        const registry = await readTokenRegistry().catch(() => ({} as Awaited<ReturnType<typeof readTokenRegistry>>));
+        const cache = await readChromeProfileCache().catch(() => null) ?? {};
+        const keys = listener.profiles === "*" ? Object.keys(registry) : listener.profiles;
+        return Response.json({ share: cred?.share.label, profiles: keys.map(k => ({ key: k, name: cache[registry[k]?.profileDir ?? ""]?.name ?? "", registered: !!registry[k] })) });
+      }
+
+      if (reqUrl.pathname === "/sessions") {
+        const denied = authCheck(req, key);
+        if (denied) return denied;
+        let live = new Set<string>();
+        try { live = new Set(readdirSync(tmpSocketRoot()).filter(f => f.endsWith(".sock")).map(f => f.slice(0, -5))); } catch {}
+        const all = listener.profiles === "*" && !cred;
+        const rows = [...sessionOwners.entries()]
+          .filter(([, o]) => all || o.owner === owner)
+          .map(([session, o]) => ({ session: o.name, profile: o.profile, client: o.label, owner: all ? o.owner : undefined, lastUsed: o.lastUsed, live: live.has(session) }))
+          .sort((a, b) => b.lastUsed - a.lastUsed);
+        return Response.json({ sessions: rows });
+      }
+
       // Serve files from output dir
       if (reqUrl.pathname.startsWith("/files/")) {
         const denied = authCheck(req, key);
         if (denied) return denied;
         const name = decodeURIComponent(reqUrl.pathname.slice(7));
         if (!isUnderDir(workDir, name)) return new Response("Forbidden", { status: 403 });
-        if (!canReadProfileFile(listener, name)) return new Response("Forbidden", { status: 403 });
+        const readable = (path: string) => canReadProfileFile(listener, path)
+          && (cred?.kind !== "device" || cred.share.profiles.some(p => path.startsWith(`${profileOutputPrefix(p)}d-${cred.device.id}/`)));
+        if (!readable(name)) return new Response("Forbidden", { status: 403 });
         const resolved = resolve(workDir, name);
         const f = file(resolved);
         if (!(await f.exists())) return new Response("Not found", { status: 404 });
         const real = realpathSync(resolved);
-        if (!isUnderDir(realpathSync(workDir), real) || !canReadProfileFile(listener, relative(realpathSync(workDir), real).replaceAll("\\", "/"))) return new Response("Forbidden", { status: 403 });
+        if (!isUnderDir(realpathSync(workDir), real) || !readable(relative(realpathSync(workDir), real).replaceAll("\\", "/"))) return new Response("Forbidden", { status: 403 });
         return new Response(f);
       }
 
@@ -615,12 +749,15 @@ export async function serve() {
         // clients / `rech status` can see trouble without an active probe.
         const degraded = consecutiveTimeouts > 0;
         if (scoped || !reqUrl.searchParams.get("deep"))
-          return Response.json({ ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded });
+          return Response.json({
+            ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded, chromeAccessProblem,
+            ...(cred ? { share: cred.share.label, kind: cred.kind, ...(cred.kind === "device" ? { device: { id: cred.device.id, name: cred.device.name, approved: cred.device.approved } } : {}), expiresAt: cred.share.expiresAt } : {}),
+          });
         // Deep probe: exercise the relay read-only via `tab-list` (opens nothing) against the
         // most-recently-used session — never a fresh one, which could spawn a browser window.
         const target = [...recentSessions.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
         if (!target)
-          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded });
+          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded, chromeAccessProblem });
         const [pbin, ...pbinArgs] = splitCommand(resolvePlaywrightCli());
         const probe = Bun.spawn([pbin, ...pbinArgs, "tab-list", `-s=${target}`], {
           cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
@@ -634,7 +771,7 @@ export async function serve() {
         const healthy = probeStatus !== -1;
         return Response.json({
           ok: healthy, bind: listenHost, relay: healthy ? "healthy" : "degraded",
-          consecutiveTimeouts, degraded: degraded || !healthy,
+          consecutiveTimeouts, degraded: degraded || !healthy, chromeAccessProblem,
         });
       }
       // A browser opening a shared URL gets copyable connect instructions. The key stays in the
@@ -675,7 +812,9 @@ export async function serve() {
             PLAYWRIGHT_MCP_USER_DATA_DIR: entry.userDataDir || "",
             PLAYWRIGHT_MCP_LOAD_EXTENSION: entry.loadExtension || "",
           };
-          body.identity.key = `scoped:${body.identity.key}`;
+          // A share's devices never share browser state with each other or with legacy links.
+          body.identity.key = cred?.kind === "device" ? `share:${cred.share.id}:${cred.device.id}:${body.identity.key}` : `scoped:${body.identity.key}`;
+          if (cred) body.identity.label = cred.share.label;
           body.env = {}; // Server-owned profile configuration wins over every client override.
         } catch (error) {
           if (Array.isArray(body?.args) && body.args.filter((a: unknown) => typeof a !== "string" || !/^-s=[a-zA-Z0-9_-]{1,64}$/.test(a))[0] === "upload")
@@ -683,7 +822,9 @@ export async function serve() {
           return Response.json({ status: 1, stdout: "", stderr: `${error instanceof Error ? error.message : String(error)}\n` }, { status: 403 });
         }
       }
-      const outputPrefix = scopedProfile ? profileOutputPrefix(scopedProfile) : "";
+      // A share device's files live under its own folder, so other devices and links on the same
+      // profile can't fetch them (see the /files check above).
+      const outputPrefix = scopedProfile ? profileOutputPrefix(scopedProfile) + (cred?.kind === "device" ? `d-${cred.device.id}/` : "") : "";
       const runWorkDir = scopedProfile ? join(workDir, outputPrefix) : workDir;
       mkdirSync(runWorkDir, { recursive: true });
       let args: string[];
@@ -692,7 +833,7 @@ export async function serve() {
       let clientEnv: Record<string, string> = {};
       if (Array.isArray(body)) {
         args = body;
-        const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
+        const clientAddr = remoteAddr();
         sessionId = createHash("sha256").update(clientAddr).digest("hex").slice(0, 8);
         clientName = clientAddr;
         log(`session from client IP: ${clientAddr} -> ${sessionId}`);
@@ -713,7 +854,7 @@ export async function serve() {
           clientName = labelBase || keyBase;
           log(`session from identity: ${clientName}${id?.profile ? ` profile:${id.profile}` : ""} [${keyBase}] -> ${sessionId}`);
         } else {
-          const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
+          const clientAddr = remoteAddr();
           sessionId = createHash("sha256").update(clientAddr).digest("hex").slice(0, 8);
           clientName = clientAddr;
           log(`session from client IP fallback: ${clientAddr} -> ${sessionId}`);
@@ -738,6 +879,8 @@ export async function serve() {
       const namespacedSession = clientSession ? `${sessionId}-${clientSession}` : sessionId;
       // Track --isolate sessions so the idle-TTL reaper can close them later.
       const nowMs = Date.now();
+      sessionOwners.set(namespacedSession, { owner, label: cred ? `${cred.share.label}/${(cred as any).device?.name ?? ""}` : clientName, profile: scopedProfile ?? (body as any)?.identity?.profile, name: clientSession || "default", lastUsed: nowMs });
+      if (sessionOwners.size > 512) sessionOwners.delete(sessionOwners.keys().next().value!);
       if (isIsoSession(namespacedSession)) isoLastUsed.set(namespacedSession, nowMs);
       else noteSession(namespacedSession, nowMs); // for the deep health probe to target
 
@@ -765,7 +908,14 @@ export async function serve() {
 
       // Resolve profile name/email → directory name
       if (!scoped && passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY) {
-        const resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        let resolved: string;
+        try {
+          resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        } catch (error) {
+          if (!(error instanceof ProfileResolutionError)) throw error;
+          log(`refused unresolvable profile "${error.profile}" (session=${namespacedSession})`);
+          return Response.json({ status: 1, stdout: "", stderr: error.message, files: [] });
+        }
         if (resolved !== passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY)
           log(`profile resolved: "${passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY}" → "${resolved}"`);
         passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY = resolved;
@@ -907,7 +1057,8 @@ export async function serve() {
       const handshakeTimeoutMs = Number.isFinite(configuredHandshakeTimeout) && configuredHandshakeTimeout > 0
         ? configuredHandshakeTimeout
         : 30_000;
-      const stderr = inferSilentExtensionFailure({
+      const tccNote = explainExtensionNotFound(`${stdout}\n${rawStderr}`, chromeAccessProblem);
+      const stderr = (tccNote ?? "") + inferSilentExtensionFailure({
         status,
         stdout,
         stderr: rawStderr,
@@ -988,6 +1139,33 @@ export async function serve() {
         // a cross-OS daemon↔client (e.g. Windows daemon serving a Linux container client).
         files: outputFiles.map((p) => (outputPrefix + p).replaceAll("\\", "/")),
       });
+  };
+
+  // WebRTC: the same handler, reached over an encrypted DataChannel. Each request carries the
+  // bearer of the credential whose room it came in on, so share checks apply unchanged.
+  const webrtcListener: Listener = { name: WEBRTC, host: "webrtc", port: 0, key: randomBytes(24).toString("base64url"), profiles: [] };
+  const webrtc = new WebrtcHost(async (req, token) => {
+    const headers = new Headers(req.headers);
+    headers.set("Authorization", `Bearer ${bearerOf(token)}`);
+    return handle(new Request(req, { headers }), webrtcListener, () => "webrtc");
+  }, log);
+
+  const startServer = (initial: Listener, reusePort = false) => Bun.serve({
+    hostname: initial.host,
+    port: initial.port,
+    // reusePort is used only as a last-resort fallback (see bindAtStartup below): if an orphaned
+    // holder can't be killed, binding with SO_REUSEADDR keeps serve up (degraded, port-shared)
+    // instead of crash-looping on EADDRINUSE. The normal path binds a clean, exclusive socket.
+    reusePort,
+    tls,
+    error(err) {
+      log(`unhandled error: ${err.message}`);
+      return Response.json({ status: 1, stdout: "", stderr: err.message }, { status: 500 });
+    },
+    async fetch(req, server) {
+      const listener = policies.get(listenerAddress(initial));
+      if (!listener) return new Response("Listener removed", { status: 403 });
+      return handle(req, listener, () => `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`);
     },
   });
 
@@ -1056,12 +1234,42 @@ export async function serve() {
     configured ||= !!config;
     applied = fingerprint;
   };
+  // Shares change independently of listeners (redeem, approve, revoke); a bad shares.json keeps
+  // the previous one, like listeners.json.
+  let appliedShares = "";
+  const reloadShares = async () => {
+    const next = await readShares();
+    // Expiry is time-based: fold "what is live right now" into the fingerprint so an expiring
+    // share or invite closes its rooms and sessions without anyone touching the file.
+    const now = Date.now();
+    const fingerprint = JSON.stringify(next) + JSON.stringify(next.shares.map(s => [!!shareProblem(s, now), !!(s.inviteExpiresAt && now >= s.inviteExpiresAt)]));
+    if (fingerprint === appliedShares) return;
+    const allowed = new Set(next.shares.filter(s => !shareProblem(s, now)).flatMap(s => s.devices.map(d => `share:${s.id}:${d.id}`)));
+    const dropped = [...sessionOwners.entries()].filter(([, o]) => o.owner.startsWith("share:") && !allowed.has(o.owner));
+    shares = next;
+    appliedShares = fingerprint;
+    // A revoked share or a removed device loses its browser sessions too.
+    if (dropped.length) {
+      const [bin, ...binArgs] = splitCommand(resolvePlaywrightCli());
+      for (const [session, o] of dropped) {
+        sessionOwners.delete(session);
+        try { Bun.spawn([bin, ...binArgs, "close", `-s=${session}`], { cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore", windowsHide: true, env: playwrightCliEnv() }); } catch {}
+        log(`closed session ${session} of ${o.label}: its share was revoked or its device removed`);
+      }
+    }
+    const creds = webrtcCredentials(next);
+    webrtc.sync(creds.map(c => ({ token: c.token, signal: c.share.signal!, label: c.kind === "device" ? `${c.share.label}/${c.device.name}` : `${c.share.label} (invite)` })));
+    if (creds.length || webrtc.size) log(`webrtc: listening for ${creds.length} share credential(s)`);
+  };
+  await reloadShares().catch(error => log(`shares.json rejected: ${error}`));
   await reload(true);
   let reloading = false;
   let lastError = "";
   setInterval(async () => {
     if (reloading) return;
     reloading = true;
+    // Independent: a broken listeners.json must not freeze revocations (and vice versa).
+    try { await reloadShares(); } catch (error) { log(`shares.json reload rejected; previous shares retained: ${error}`); }
     try { await reload(); lastError = ""; }
     catch (error) {
       const message = String(error);