handmux 0.23.0 → 0.25.0

package/src/browser/profilePersistence.js

@@ -1,241 +0,0 @@
-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/publicProxy.js

@@ -1,175 +0,0 @@
-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';
-
-function sessionChannel(pathname) {
-  const descriptor = String(pathname || '').split('/')[1] || '';
-  return descriptor.match(/\*([A-Za-z0-9_-]{1,128})$/)?.[1] || null;
-}
-
-function sessionUnavailableHtml(pathname) {
-  const channel = JSON.stringify(sessionChannel(pathname));
-  return `<!doctype html><meta charset="utf-8">
-<script>parent.postMessage({source:'handmux-browser',channel:${channel},type:'session-unavailable'},'*')</script>
-<pre>{"error":"browser session unavailable"}</pre>`;
-}
-
-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 expectsDocument(req) {
-  const destination = String(req.headers['sec-fetch-dest'] || '').toLowerCase();
-  const accept = String(req.headers.accept || '').toLowerCase();
-  return destination === 'document' || destination === 'iframe' || accept.includes('text/html');
-}
-
-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)) {
-        res.setHeader('Cache-Control', 'no-store');
-        if (expectsDocument(req)) return res.status(403).type('html').send(sessionUnavailableHtml(pathname));
-        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

@@ -1,154 +0,0 @@
-import express from 'express';
-import { browserLabelForOrigin } from './originLabel.js';
-import { browserRequestOrigin } from './publicProxy.js';
-import { normalizeSiteVersion } from './siteVersion.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' });
-    const siteVersion = normalizeSiteVersion(req.body?.siteVersion);
-    if (!siteVersion) return res.status(400).json({ error: 'bad browser site version' });
-    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,
-        siteVersion,
-        sourceUserAgent: req.get('user-agent') || '',
-      });
-      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' });
-    const siteVersion = normalizeSiteVersion(req.body?.siteVersion);
-    if (!siteVersion) return res.status(400).json({ error: 'bad browser site version' });
-    try {
-      const origin = wildcardOrigin(publicBase, new URL(url).origin);
-      const lease = await browser.navigateLease(
-        req.params.tabId,
-        req.body.url,
-        req.browserDeviceId,
-        origin,
-        siteVersion,
-        req.get('user-agent') || '',
-      );
-      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

@@ -1,78 +0,0 @@
-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;
-    },
-  };
-}