handmux 0.20.3 → 0.22.0

package/src/browser/profilePersistence.js

@@ -0,0 +1,241 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes as nodeRandomBytes,
+} from 'node:crypto';
+import defaultFs from 'node:fs/promises';
+import path from 'node:path';
+
+const AUTHENTICATION_ERROR = 'browser profile authentication failed';
+
+function profileHash(deviceId) {
+  return createHash('sha256').update(deviceId).digest('hex');
+}
+
+function authenticationError() {
+  return new Error(AUTHENTICATION_ERROR);
+}
+
+export function createBrowserProfilePersistence({
+  dir,
+  keyFile,
+  fs = defaultFs,
+  randomBytes = nodeRandomBytes,
+}) {
+  let keyPromise = null;
+  const pending = new Set();
+
+  const ensureDir = async () => {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700);
+  };
+
+  const loadKey = async () => {
+    await ensureDir();
+    try {
+      await fs.chmod(keyFile, 0o600);
+      const key = await fs.readFile(keyFile);
+      if (key.length !== 32) throw authenticationError();
+      return key;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+
+    const key = randomBytes(32);
+    let handle;
+    try {
+      handle = await fs.open(keyFile, 'wx', 0o600);
+      await handle.writeFile(key);
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      return key;
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      if (error?.code === 'EEXIST') {
+        await fs.chmod(keyFile, 0o600);
+        const existing = await fs.readFile(keyFile);
+        if (existing.length !== 32) throw authenticationError();
+        return existing;
+      }
+      await fs.unlink(keyFile).catch(() => {});
+      throw error;
+    }
+  };
+
+  const key = () => {
+    if (!keyPromise) keyPromise = loadKey();
+    return keyPromise;
+  };
+  const profilePath = (deviceId) => path.join(dir, `${profileHash(deviceId)}.profile`);
+  const metadataPath = (deviceId) => path.join(dir, `${profileHash(deviceId)}.meta`);
+
+  const track = (operation) => {
+    pending.add(operation);
+    operation.then(
+      () => pending.delete(operation),
+      () => pending.delete(operation),
+    );
+    return operation;
+  };
+
+  const read = async (deviceId) => {
+    let raw;
+    const target = profilePath(deviceId);
+    await ensureDir();
+    try {
+      await fs.chmod(target, 0o600);
+      raw = await fs.readFile(target, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+
+    try {
+      const deviceHash = profileHash(deviceId);
+      const envelope = JSON.parse(raw);
+      if (envelope?.v !== 1
+        || typeof envelope.iv !== 'string'
+        || typeof envelope.tag !== 'string'
+        || typeof envelope.data !== 'string') {
+        throw authenticationError();
+      }
+      const iv = Buffer.from(envelope.iv, 'base64');
+      const tag = Buffer.from(envelope.tag, 'base64');
+      if (iv.length !== 12 || tag.length !== 16) throw authenticationError();
+      const decipher = createDecipheriv('aes-256-gcm', await key(), iv);
+      decipher.setAAD(Buffer.from(`handmux-browser-profile:v1:${deviceHash}`));
+      decipher.setAuthTag(tag);
+      return Buffer.concat([
+        decipher.update(Buffer.from(envelope.data, 'base64')),
+        decipher.final(),
+      ]).toString('utf8');
+    } catch {
+      throw authenticationError();
+    }
+  };
+
+  const write = (deviceId, serializedJar) => track((async () => {
+    const deviceHash = profileHash(deviceId);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', await key(), iv);
+    cipher.setAAD(Buffer.from(`handmux-browser-profile:v1:${deviceHash}`));
+    const encrypted = Buffer.concat([
+      cipher.update(serializedJar, 'utf8'),
+      cipher.final(),
+    ]);
+    const envelope = {
+      v: 1,
+      iv: iv.toString('base64'),
+      tag: cipher.getAuthTag().toString('base64'),
+      data: encrypted.toString('base64'),
+    };
+    const target = profilePath(deviceId);
+    const temp = `${target}.tmp-${process.pid}-${randomBytes(12).toString('hex')}`;
+    let handle;
+    try {
+      handle = await fs.open(temp, 'wx', 0o600);
+      await handle.writeFile(JSON.stringify(envelope), 'utf8');
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      await fs.rename(temp, target);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      await fs.unlink(temp).catch(() => {});
+      throw error;
+    }
+  })());
+
+  const remove = (deviceId) => track(
+    fs.unlink(profilePath(deviceId)).catch((error) => {
+      if (error?.code !== 'ENOENT') throw error;
+    }),
+  );
+
+  const readMetadata = async (deviceId) => {
+    const target = metadataPath(deviceId);
+    await ensureDir();
+    try {
+      await fs.chmod(target, 0o600);
+      const value = JSON.parse(await fs.readFile(target, 'utf8'));
+      if (typeof value?.persist !== 'boolean'
+        || ![1, 7, 30, null].includes(value?.retentionDays)
+        || (value?.noLeaseSince !== null && !Number.isFinite(value?.noLeaseSince))) {
+        throw new Error('invalid browser profile metadata');
+      }
+      return value;
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+  };
+
+  const writeMetadata = (deviceId, metadata) => track((async () => {
+    await ensureDir();
+    const target = metadataPath(deviceId);
+    const temp = `${target}.tmp-${process.pid}-${randomBytes(12).toString('hex')}`;
+    let handle;
+    try {
+      handle = await fs.open(temp, 'wx', 0o600);
+      await handle.writeFile(JSON.stringify(metadata), 'utf8');
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      await fs.rename(temp, target);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      await fs.unlink(temp).catch(() => {});
+      throw error;
+    }
+  })());
+
+  const removeMetadata = (deviceId) => track(
+    fs.unlink(metadataPath(deviceId)).catch((error) => {
+      if (error?.code !== 'ENOENT') throw error;
+    }),
+  );
+
+  const pruneExpiredProfiles = (currentTime = Date.now()) => track((async () => {
+    await ensureDir();
+    const names = await fs.readdir(dir);
+    let removed = 0;
+    for (const name of names) {
+      const match = name.match(/^([0-9a-f]{64})\.meta$/);
+      if (!match) continue;
+      const metadataFile = path.join(dir, name);
+      let metadata;
+      try {
+        metadata = JSON.parse(await fs.readFile(metadataFile, 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!metadata?.persist
+        || metadata.retentionDays === null
+        || ![1, 7, 30].includes(metadata.retentionDays)
+        || !Number.isFinite(metadata.noLeaseSince)) continue;
+      if (metadata.noLeaseSince + metadata.retentionDays * 24 * 60 * 60 * 1000 > currentTime) continue;
+      await Promise.all([
+        fs.unlink(path.join(dir, `${match[1]}.profile`)).catch((error) => {
+          if (error?.code !== 'ENOENT') throw error;
+        }),
+        fs.unlink(metadataFile).catch((error) => {
+          if (error?.code !== 'ENOENT') throw error;
+        }),
+      ]);
+      removed += 1;
+    }
+    return removed;
+  })());
+
+  const close = async () => {
+    const results = await Promise.allSettled([...pending]);
+    const failed = results.find((result) => result.status === 'rejected');
+    if (failed) throw failed.reason;
+  };
+
+  return {
+    read, write, remove, readMetadata, writeMetadata, removeMetadata, pruneExpiredProfiles, close,
+  };
+}

package/src/browser/protocol.js

@@ -0,0 +1 @@
+export const BROWSER_INTERNAL_HEADER = 'x-handmux-browser-internal';

package/src/browser/publicProxy.js

@@ -0,0 +1,153 @@
+import http from 'node:http';
+import net from 'node:net';
+import { isBrowserBootstrapPath } from './bootstrap.js';
+import { classifyIp } from './targetPolicy.js';
+
+const SERVICE_PATHS = new Set([
+  '/hammerhead.js',
+  '/task.js',
+  '/iframe-task.js',
+  '/messaging',
+  '/transport-worker.js',
+  '/worker-hammerhead.js',
+]);
+const DEVICE_COOKIE = 'tw_browser_device';
+
+export function isBrowserServicePath(pathname) {
+  return SERVICE_PATHS.has(String(pathname || '').split('?')[0]);
+}
+
+function cookieValue(raw, name) {
+  for (const part of String(raw || '').split(';')) {
+    const [key, ...rest] = part.trim().split('=');
+    if (key === name) return rest.join('=');
+  }
+  return null;
+}
+
+function browserTarget(browser, req, deviceId) {
+  const pathname = String(req.url || '').split('?')[0];
+  if (!claimedBrowserRequest(req)) return null;
+  if (typeof browser.resolvePublicRequest === 'function') {
+    return browser.resolvePublicRequest(pathname, deviceId, browserRequestOrigin(req));
+  }
+  const allowed = isBrowserServicePath(pathname) ? browser.hasDevice(deviceId) : browser.ownsPublicPath(pathname, deviceId);
+  return allowed ? { port: browser.internalPorts[0] } : null;
+}
+
+function isLoopback(address) {
+  return classifyIp(address) === 'loopback';
+}
+
+export function browserRequestOrigin(req) {
+  const forwardedProto = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim();
+  const protocol = isLoopback(req.socket?.remoteAddress) && (forwardedProto === 'http' || forwardedProto === 'https')
+    ? forwardedProto
+    : (req.socket?.encrypted ? 'https' : 'http');
+  const host = req.headers.host;
+  if (!host) return null;
+  try { return new URL(`${protocol}://${host}`).origin; } catch { return null; }
+}
+
+export function claimedBrowserRequest(req) {
+  const pathname = String(req.url || '').split('?')[0];
+  return isBrowserBootstrapPath(pathname)
+    || isBrowserServicePath(pathname)
+    || String(pathname).split('/')[1]?.startsWith('_browser-');
+}
+
+function filteredCookie(raw) {
+  const values = String(raw || '')
+    .split(';')
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .filter((value) => !value.startsWith('tw_preview=') && !value.startsWith(`${DEVICE_COOKIE}=`));
+  return values.join('; ');
+}
+
+function upstreamHeaders(headers, port, token) {
+  const out = { ...headers, host: `127.0.0.1:${port}` };
+  if (token && out.authorization === `Bearer ${token}`) delete out.authorization;
+  delete out['proxy-authorization'];
+  if (out.cookie) {
+    out.cookie = filteredCookie(out.cookie);
+    if (!out.cookie) delete out.cookie;
+  }
+  return out;
+}
+
+export function createBrowserPublicProxy({
+  browser,
+  browserBootstrap,
+  token,
+  request = http.request,
+  connect = net.connect,
+} = {}) {
+  const handler = (req, res, next) => {
+    if (!browser) return next();
+    const pathname = String(req.url || '').split('?')[0];
+    if (isBrowserBootstrapPath(pathname)) {
+      const origin = browserRequestOrigin(req);
+      const bootstrap = browserBootstrap?.consume(pathname, origin);
+      if (!bootstrap) return res.status(403).json({ error: 'browser bootstrap unavailable' });
+      const secure = origin?.startsWith('https://') ? '; Secure' : '';
+      res.setHeader('Cache-Control', 'no-store');
+      res.setHeader('Set-Cookie', `${DEVICE_COOKIE}=${bootstrap.deviceId}; Path=/; HttpOnly; SameSite=Strict${secure}`);
+      return res.redirect(
+        bootstrap.preserveMethod ? (bootstrap.redirectStatus || 307) : 302,
+        bootstrap.url,
+      );
+    }
+    const deviceId = cookieValue(req.headers.cookie, DEVICE_COOKIE);
+    const target = browserTarget(browser, req, deviceId);
+    if (!target) {
+      if (claimedBrowserRequest(req)) return res.status(403).json({ error: 'browser session unavailable' });
+      return next();
+    }
+    const { port } = target;
+    const upstream = request({
+      hostname: '127.0.0.1',
+      port,
+      method: req.method,
+      path: req.originalUrl || req.url,
+      headers: upstreamHeaders(req.headers, port, token),
+    }, (incoming) => {
+      res.writeHead(incoming.statusCode || 502, incoming.headers);
+      incoming.pipe(res);
+      res.once('close', () => { if (!res.writableEnded) incoming.destroy(); });
+    });
+    const abort = () => upstream.destroy();
+    req.once('aborted', abort);
+    res.once('close', () => { if (!res.writableEnded) abort(); });
+    upstream.on('error', () => {
+      if (res.destroyed) return;
+      if (!res.headersSent) res.status(502).json({ error: 'browser proxy unavailable' });
+      else res.destroy();
+    });
+    req.pipe(upstream);
+  };
+
+  const onUpgrade = (req, socket, head) => {
+    const deviceId = cookieValue(req.headers.cookie, DEVICE_COOKIE);
+    const target = browser && browserTarget(browser, req, deviceId);
+    if (!target) return false;
+    const { port } = target;
+    const upstream = connect({ host: '127.0.0.1', port });
+    upstream.once('connect', () => {
+      const headers = upstreamHeaders(req.headers, port, token);
+      const lines = [`${req.method || 'GET'} ${req.url} HTTP/${req.httpVersion || '1.1'}`];
+      for (const [name, value] of Object.entries(headers)) {
+        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+        else if (value != null) lines.push(`${name}: ${value}`);
+      }
+      upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+      if (head?.length) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    });
+    upstream.once('error', () => socket.destroy());
+    socket.once('error', () => upstream.destroy());
+    return true;
+  };
+
+  return { handler, onUpgrade };
+}

package/src/browser/routes.js

@@ -0,0 +1,145 @@
+import express from 'express';
+import { browserLabelForOrigin } from './originLabel.js';
+import { browserRequestOrigin } from './publicProxy.js';
+
+const RETENTION_DAYS = new Set([1, 7, 30, null]);
+const DEVICE_ID = /^[A-Za-z0-9_-]{32,128}$/;
+const TAB_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const DEVICE_COOKIE = 'tw_browser_device';
+
+function previewBase(raw) {
+  if (!raw) return null;
+  const value = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  return new URL(value);
+}
+
+function wildcardOrigin(base, targetOrigin) {
+  const url = new URL(base.origin);
+  url.hostname = `${browserLabelForOrigin(targetOrigin)}.${base.hostname}`;
+  return url.origin;
+}
+
+function normalizedTarget(value) {
+  if (typeof value !== 'string' || !value) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizedHttpOrigin(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+export function browserRoutes({
+  browser,
+  previewDomain = null,
+  browserBootstrap = null,
+}) {
+  const router = express.Router();
+  const publicBase = previewBase(previewDomain);
+
+  router.use((req, res, next) => {
+    const deviceId = req.get('x-handmux-browser-device');
+    if (!DEVICE_ID.test(deviceId || '')) return res.status(400).json({ error: 'browser device id required' });
+    req.browserDeviceId = deviceId;
+    const origin = browserRequestOrigin(req);
+    const secure = origin?.startsWith('https://') ? '; Secure' : '';
+    res.append('Set-Cookie', `${DEVICE_COOKIE}=${deviceId}; Path=/; HttpOnly; SameSite=Strict${secure}`);
+    next();
+  });
+
+  const responseLease = (lease, deviceId) => {
+    if (!lease) return null;
+    const url = browserBootstrap.issue({
+      url: lease.url,
+      origin: new URL(lease.url).origin,
+      deviceId,
+    });
+    return { ...lease, url };
+  };
+
+  router.put('/leases/:tabId', async (req, res, next) => {
+    if (!browser || !publicBase) return res.status(503).json({ error: 'browser proxy unavailable' });
+    if (!TAB_ID.test(req.params.tabId)) return res.status(400).json({ error: 'bad browser tab id' });
+    const url = normalizedTarget(req.body?.url);
+    if (!url) return res.status(400).json({ error: 'browser URL must use http or https' });
+    try {
+      const origin = wildcardOrigin(publicBase, new URL(url).origin);
+      const lease = await browser.putLease({
+        tabId: req.params.tabId,
+        url: req.body.url,
+        origin,
+        deviceId: req.browserDeviceId,
+      });
+      return res.json(responseLease(lease, req.browserDeviceId));
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.post('/leases/:tabId/navigate', async (req, res, next) => {
+    if (!browser || !publicBase) return res.status(503).json({ error: 'browser proxy unavailable' });
+    if (!TAB_ID.test(req.params.tabId)) return res.status(400).json({ error: 'bad browser tab id' });
+    const url = normalizedTarget(req.body?.url);
+    if (!url) return res.status(400).json({ error: 'browser URL must use http or https' });
+    try {
+      const origin = wildcardOrigin(publicBase, new URL(url).origin);
+      const lease = await browser.navigateLease(
+        req.params.tabId,
+        req.body.url,
+        req.browserDeviceId,
+        origin,
+      );
+      if (!lease) return res.status(404).json({ error: 'browser proxy lease not found' });
+      return res.json(responseLease(lease, req.browserDeviceId));
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.delete('/leases/:tabId', (req, res) => {
+    if (!browser) return res.status(503).json({ error: 'browser proxy unavailable' });
+    if (!browser.deleteLease(req.params.tabId, req.browserDeviceId)) {
+      return res.status(404).json({ error: 'browser proxy lease not found' });
+    }
+    return res.status(204).end();
+  });
+
+  router.put('/profile', async (req, res, next) => {
+    const { persist, retentionDays } = req.body || {};
+    if (typeof persist !== 'boolean' || !RETENTION_DAYS.has(retentionDays)) {
+      return res.status(400).json({ error: 'bad browser profile preferences' });
+    }
+    try {
+      return res.json(await browser.configureDeviceProfile(
+        req.browserDeviceId,
+        { persist, retentionDays },
+      ));
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.post('/profile/clear', async (req, res, next) => {
+    const rawOrigin = req.body?.origin;
+    const origin = rawOrigin === null ? null : normalizedHttpOrigin(rawOrigin);
+    if (origin === null && rawOrigin !== null) {
+      return res.status(400).json({ error: 'bad browser profile clear request' });
+    }
+    try {
+      return res.json(await browser.clearDeviceProfile(req.browserDeviceId, { origin }));
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  return router;
+}

package/src/browser/sessionStore.js

@@ -0,0 +1,78 @@
+export function createBrowserSessionStore({
+  now = Date.now,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  onExpire = () => {},
+} = {}) {
+  const tabs = new Map();
+
+  const cancel = (tab) => {
+    if (tab.timer != null) clearTimer(tab.timer);
+    tab.timer = null;
+    tab.hiddenAt = null;
+    tab.expiresAt = null;
+  };
+
+  const remove = (id) => {
+    const tab = tabs.get(id);
+    if (!tab) return null;
+    if (tab.timer != null) clearTimer(tab.timer);
+    tabs.delete(id);
+    const { timer: _timer, ...out } = tab;
+    return out;
+  };
+
+  const view = (tab) => {
+    if (!tab) return null;
+    const { timer: _timer, ...out } = tab;
+    return out;
+  };
+
+  return {
+    add(input) {
+      if (tabs.has(input.id)) throw new Error(`browser tab already exists: ${input.id}`);
+      const mode = input.mode === 'direct' ? 'direct' : 'proxy';
+      const tab = { ...input, mode, visible: true, hiddenAt: null, expiresAt: null, timer: null };
+      tabs.set(tab.id, tab);
+      return view(tab);
+    },
+
+    get(id) { return view(tabs.get(id)); },
+
+    list() { return [...tabs.values()].map(view); },
+
+    update(id, patch) {
+      const tab = tabs.get(id);
+      if (!tab) return null;
+      Object.assign(tab, patch);
+      return view(tab);
+    },
+
+    setVisible(id, visible, closeAfterMinutes) {
+      const tab = tabs.get(id);
+      if (!tab) return null;
+      cancel(tab);
+      tab.visible = !!visible;
+      if (!tab.visible) {
+        tab.hiddenAt = now();
+        if (closeAfterMinutes != null) {
+          const delay = closeAfterMinutes * 60_000;
+          tab.expiresAt = tab.hiddenAt + delay;
+          tab.timer = setTimer(() => {
+            const expired = remove(id);
+            if (expired) onExpire(expired, 'expired');
+          }, delay);
+        }
+      }
+      return view(tab);
+    },
+
+    remove,
+
+    close() {
+      const removed = [];
+      for (const id of [...tabs.keys()]) removed.push(remove(id));
+      return removed;
+    },
+  };
+}