// The live view's parts, used by `hand-over.mjs open --view` and `install-view`: what a computer needs
// to show one, the install, the screen source, the fit, the routes, and a request's body. Node built-ins, plus `tar`.
import { spawn, spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { delimiter, dirname, join, relative } from 'node:path';
import { serverDisplay, serverPid, serverWindow } from '../../../scripts/browse.mjs';
import { alive, killTunnel } from './lib/tunnel.mjs';
/** The one viewer version WongStack has tried: its source release and the fingerprint of its `core/` and
* `vendor/` files. The three move together, by hand; update.mjs only reads the version. */
export const VIEWER = { version: '1.6.0', url: 'https://github.com/novnc/noVNC/archive/refs/tags/v1.6.0.tar.gz', sha256: '25e27eaae3c616d207ea020ef40d3ba066f4dbaf47ef506fd0457975a137d17a' };
/** What each tool is for, and what its install needs, as the person is told. */
export const TOOLS = {
x11vnc: 'x11vnc shows the browser\'s screen. It is a system package, so it needs admin rights.',
xdotool: 'xdotool keeps the page\'s window in front. It is a system package, so it needs admin rights.',
novnc: `noVNC ${VIEWER.version} draws that screen on the link's page. It goes in your home folder.`,
};
export const OFF_LINUX = 'A live view needs Linux, where the browser runs on a virtual screen it can show.';
export const VIEW_ROUTES = new Set(['/view', '/fit', '/give', '/show', '/watch', '/take']);
/** A watch link's buttons, each its route: the person takes the browser, or hands it back. */
const WATCH_ACTIONS = new Set(['/take', '/give']);
const BODY_MOST = 16 * 1024;
const FITS = ['phone', 'wide'];
const PHONE_WIDTH = 480;
const PACKAGES = ['x11vnc', 'xdotool'];
const INSTALL = ['install', '-y', '--no-install-recommends', ...PACKAGES];
/** The one command for the person, where the agent can not install the system tools. */
export const MANUAL = `sudo apt-get ${INSTALL.join(' ')}`;
const HASHED = ['core', 'vendor'];
const KEPT = [...HASHED, 'LICENSE.txt'];
const DOWNLOAD_MS = 120_000;
const INSTALL_MS = 10 * 60_000;
const SOURCE_WAIT_MS = 10_000;
const TOOL_MS = 5000;
const sleep = ms => new Promise(done => setTimeout(done, ms));
const readText = file => { try { return readFileSync(file, 'utf8'); } catch { return ''; } };
const sha256 = data => createHash('sha256').update(data).digest('hex');
/** A command's file: the one `HANDOVER_<NAME>_BIN` names, for tests, else the first on PATH; null with none. */
export function findTool(name, env = process.env) {
const named = env[`HANDOVER_${name.toUpperCase().replace('-', '_')}_BIN`];
const files = named ? [named] : (env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name));
return files.find(file => { try { accessSync(file, constants.X_OK); return true; } catch { return false; } }) ?? null;
}
/** The folder the pinned viewer is kept in. */
export function viewerDir(home = homedir(), { version } = VIEWER) {
return join(home, '.wong-stack', 'live-view', `novnc-${version}`);
}
/** How this computer shows the browser: `window` when the running browser has its own window, else `unsupported` off
* Linux, else `missing`, each absent tool. */
export function checkView({ platform = process.platform, env = process.env, home = homedir(), viewer = VIEWER, window = serverWindow() } = {}) {
if (window) return { window: true, missing: [] };
if (platform !== 'linux') return { unsupported: OFF_LINUX, missing: [] };
const present = name => (name === 'novnc' ? existsSync(join(viewerDir(home, viewer), 'core', 'rfb.js')) : Boolean(findTool(name, env)));
return { missing: Object.keys(TOOLS).filter(name => !present(name)) };
}
/** The viewer's fingerprint: the SHA-256 of a `sha256sum` line for each file under `core/` and
* `vendor/`, sorted by path. Null when a folder is absent or holds anything but plain files. */
export function fingerprint(dir) {
const lines = [];
try {
for (const entry of HASHED.flatMap(top => readdirSync(join(dir, top), { recursive: true, withFileTypes: true }))) {
if (entry.isDirectory()) continue;
if (!entry.isFile()) return null;
const file = join(entry.parentPath, entry.name);
lines.push(`${sha256(readFileSync(file))} ${relative(dir, file)}\n`);
}
} catch {
return null;
}
const path = line => line.slice(66);
return sha256(lines.sort((a, b) => (path(a) < path(b) ? -1 : 1)).join(''));
}
/** Downloads `viewer`'s source release and keeps its `core/`, `vendor/`, and licence in `dir`, only
* when every file matches the recorded fingerprint. Throws, with nothing installed, when it does not. */
export async function installViewer(viewer, dir) {
mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
const scratch = mkdtempSync(join(dirname(dir), 'download-'));
try {
const response = await fetch(viewer.url, { signal: AbortSignal.timeout(DOWNLOAD_MS) }).catch(() => null);
if (!response?.ok) throw new Error(`the viewer could not be downloaded from ${viewer.url}`);
const archive = join(scratch, 'viewer.tar.gz');
writeFileSync(archive, Buffer.from(await response.arrayBuffer()));
spawnSync('tar', ['-xzf', archive, '-C', scratch, '--strip-components=1', ...KEPT.map(name => `noVNC-${viewer.version}/${name}`)], { stdio: 'ignore' });
rmSync(archive);
const found = fingerprint(scratch);
if (found !== viewer.sha256) throw new Error(`the viewer's files are not the ones WongStack tried: their fingerprint is ${found ?? 'unreadable'}, not ${viewer.sha256}. Nothing was installed`);
rmSync(dir, { recursive: true, force: true });
renameSync(scratch, dir);
} finally {
rmSync(scratch, { recursive: true, force: true });
}
}
/** How `apt-get` runs here with no password, as a command line, or null: as root, or through `sudo -n`. */
function aptCommand(env, uid) {
const apt = findTool('apt-get', env);
if (!apt) return null;
if (uid === 0) return [apt];
const sudo = findTool('sudo', env);
return sudo && spawnSync(sudo, ['-n', 'true'], { stdio: 'ignore' }).status === 0 ? [sudo, '-n', apt] : null;
}
/** Installs what `checkView` finds missing: `installed`, `unsupported` off Linux, or `manual`, with nothing
* installed, when `apt-get` can not run without a password. Throws on a fingerprint miss or a failed install. */
export async function installView({ platform = process.platform, env = process.env, home = homedir(), uid = process.getuid?.(), viewer = VIEWER } = {}) {
const { unsupported, missing } = checkView({ platform, env, home, viewer, window: false });
if (unsupported) return 'unsupported';
const packages = missing.some(name => PACKAGES.includes(name));
const apt = packages ? aptCommand(env, uid) : [];
if (!apt) return 'manual';
if (missing.includes('novnc')) await installViewer(viewer, viewerDir(home, viewer));
if (packages && spawnSync(apt[0], [...apt.slice(1), ...INSTALL], { stdio: ['ignore', 2, 2], timeout: INSTALL_MS }).status !== 0) throw new Error('apt-get did not install x11vnc and xdotool; see its lines above');
const still = checkView({ platform, env, home, viewer, window: false }).missing;
if (still.length) throw new Error(`still missing after the install: ${still.join(', ')}`);
return 'installed';
}
/** The processes whose parent is `pid`, as `{pid, name}`. */
function childrenOf(pid, proc) {
const children = [];
for (const entry of readdirSync(proc).filter(name => /^\d+$/.test(name))) {
const stat = readText(join(proc, entry, 'stat'));
const close = stat.lastIndexOf(')');
if (Number(stat.slice(close + 2).split(' ')[1]) === pid) children.push({ pid: Number(entry), name: stat.slice(stat.indexOf('(') + 1, close) });
}
return children;
}
/** The kernel's number for each socket `pid` holds open. */
function socketsOf(pid, proc) {
const fds = join(proc, String(pid), 'fd');
let names;
try { names = readdirSync(fds); } catch { return []; }
return names.flatMap(fd => {
try { return /^socket:\[(\d+)\]$/.exec(readlinkSync(join(fds, fd)))?.[1] ?? []; } catch { return []; }
});
}
/** A `/proc/net` table's rows, each split into its columns. */
const rows = (proc, table) => readText(join(proc, 'net', table)).split('\n').map(line => line.trim().split(/\s+/));
/** The display an `Xvfb` process serves, from the X socket it holds open. */
function xvfbDisplay(pid, proc) {
const paths = new Map(rows(proc, 'unix').map(columns => [columns[6], columns[7]]));
for (const inode of socketsOf(pid, proc)) {
const display = /^\/tmp\/\.X11-unix\/X(\d+)$/.exec(paths.get(inode) ?? '')?.[1];
if (display) return `:${display}`;
}
return null;
}
/** The X display the browser draws on, or null when it has none: the one its server recorded, else `DISPLAY` of
* the server's `camoufox-bin` child, else the socket of its `Xvfb` child. */
export function screenOf(server = serverPid(), proc = '/proc', recorded = proc === '/proc' && server === serverPid() ? serverDisplay() : null) {
if (recorded) return recorded;
const children = server ? childrenOf(server, proc) : [];
for (const { pid } of children.filter(child => child.name === 'camoufox-bin')) {
const display = readText(join(proc, String(pid), 'environ')).split('\0').find(entry => entry.startsWith('DISPLAY='))?.slice(8);
if (display) return display;
}
const xvfb = children.find(child => child.name === 'Xvfb');
return xvfb ? xvfbDisplay(xvfb.pid, proc) : null;
}
/** True when `pid` holds a listening TCP socket, or when the kernel's list of them can not be read. */
export function listensOnTcp(pid, proc = '/proc') {
if (!existsSync(join(proc, 'net', 'tcp'))) return true;
const listening = new Set(['tcp', 'tcp6'].flatMap(table => rows(proc, table)).filter(columns => columns[3] === '0A').map(columns => columns[9]));
return socketsOf(pid, proc).some(inode => listening.has(inode));
}
/** The screen source's socket in its folder. */
export const socketOf = dir => join(dir, 'screen.sock');
/** Stops the screen source and removes its folder. */
export async function stopSource({ sourcePid, dir }) {
await killTunnel(sourcePid);
rmSync(dir, { recursive: true, force: true });
}
/** Starts `x11vnc` on a Unix socket in `dir`; throws if it holds a TCP listener. `-rfbport 0` or `-rfbportv6 0`
* alone leaves a port open with no password; `-localhost` is left out, since it drops every Unix-socket client. */
export async function startSource(display, dir) {
const socket = socketOf(dir);
rmSync(socket, { force: true });
const bin = findTool('x11vnc');
const child = bin && spawn(bin, ['-display', display, '-unixsock', socket, '-rfbport', '0', '-rfbportv6', '0', '-nopw', '-forever', '-shared', '-noxdamage', '-quiet'], { detached: true, stdio: 'ignore' });
child?.on('error', () => {}).unref();
const end = Date.now() + SOURCE_WAIT_MS;
while (!existsSync(socket) && alive(child?.pid) && Date.now() < end) await sleep(50);
const fault = !existsSync(socket) ? 'The screen tool, x11vnc, did not start.' : listensOnTcp(child.pid) ? 'The screen tool, x11vnc, opened a network port, so it was stopped and no link was opened.' : null;
if (!fault) return { dir, sourcePid: child.pid };
await stopSource({ sourcePid: child?.pid, dir });
throw new Error(fault);
}
/** Runs xdotool on `display` and resolves to what it prints; throws when it is missing or fails. */
function xdotool(display, ...args) {
const bin = findTool('xdotool');
const out = bin && spawnSync(bin, args, { env: { ...process.env, DISPLAY: display }, encoding: 'utf8', timeout: TOOL_MS });
if (out?.status !== 0) throw new Error(`xdotool ${args[0]} failed`);
return out.stdout;
}
/** The screen's size, `{width, height}`. */
function screenSize(display) {
const [width, height] = xdotool(display, 'getdisplaygeometry').trim().split(/\s+/).map(Number);
if (!(width > 0 && height > 0)) throw new Error('xdotool gave no screen size');
return { width, height };
}
/** A window's place and size on `display`, as `{id, x, y, width, height}`. */
function windowShape(display, id) {
const shape = xdotool(display, 'getwindowgeometry', '--shell', id);
const number = name => Number(new RegExp(`^${name}=(-?\\d+)$`, 'm').exec(shape)?.[1]);
return { id, x: number('X'), y: number('Y'), width: number('WIDTH'), height: number('HEIGHT') };
}
/** Each browser page's window on `display`, as `{id, x, y, width, height}`; none when the search finds none.
* xdotool finds the `Navigator` window by `--classname`; `--class` finds none. */
function pageWindows(display) {
try {
return xdotool(display, 'search', '--classname', 'Navigator').split('\n').filter(Boolean).map(id => windowShape(display, id));
} catch {
return [];
}
}
/** Sizes each page window bigger than the screen to the screen, at its corner: on an add-on's page the browser keeps
* the page's height, and a window from a bigger start would hang off the screen, toolbar included. */
function fitWindows(display, screen) {
for (const win of pageWindows(display).filter(each => each.width > screen.width || each.height > screen.height)) {
try {
xdotool(display, 'windowsize', win.id, String(screen.width), String(screen.height), 'windowmove', win.id, '0', '0');
} catch { /* the next fit tries again */ }
}
}
/** The id of each browser pop-up that shows on `display`, such as an add-on's toolbar pop-up or a menu: Firefox draws
* each as a window of its own, X instance name `Camoufox`, where a page's window is `Navigator`. */
function popupIds(display) {
try { return xdotool(display, 'search', '--onlyvisible', '--classname', '^Camoufox$').split('\n').filter(Boolean); } catch { return []; }
}
/** True while a browser pop-up shows on `display`. */
export const popupOpen = display => popupIds(display).length > 0;
/** Moves each pop-up in `ids` whose right edge passes `strip` left until it ends there, or starts at 0 when wider. No
* raise or focus: focus closes it. Firefox opens a pop-up rightward under its button, past a phone's strip. */
function popupsIntoStrip(display, ids, strip) {
for (const id of ids) {
try {
const win = windowShape(display, id);
if (win.x + win.width > strip) xdotool(display, 'windowmove', id, String(Math.max(0, strip - win.width)), String(win.y));
} catch { /* the next poll tries again */ }
}
}
/** The window to keep in front among `fits`: one the person just opened, such as a password manager's own window, else
* the one kept last, else the narrowest. `seen` holds every window id the view has listed before. */
export function keptWindow(fits, seen, kept) {
const opened = seen.size ? fits.filter(win => !seen.has(win.id)) : [];
return opened.at(-1) ?? fits.find(win => win.id === kept) ?? [...fits].sort((a, b) => a.width - b.width)[0];
}
/** Sets the page's first size back and stops the screen source: what every end of a view does. */
export async function endView(view, page) {
if (view.size) await page.resize(...view.size).catch(() => {});
await stopSource(view);
}
/** The open view's fit and source, for the watcher, on the shown `page`, which `show` sets. Each step waits for the
* one before it, and none acts once `end` has run. */
export function liveView(view, page = null) {
let kind = 'wide';
let screen = null;
let bar = null;
// The last answer came from the password manager's page.
let addon = false;
let ended = false;
let last = Promise.resolve();
const seen = new Set();
let kept = null;
// In a phone fit, the width of the window kept in front: the browser's stops near 500, past the page's 480.
let keptWidth = 0;
const inTurn = job => {
const run = last.then(job);
last = run.catch(() => {});
return run;
};
const fitted = () => ({ width: kind === 'phone' ? Math.min(PHONE_WIDTH, screen.width) : screen.width, height: screen.height - (bar ?? 0) });
/** The strip of the screen the view shows: in a phone fit, the kept window's whole width, toolbar included. A window
* as wide as the screen, as `fitWindows` leaves one, stays cropped: shown whole, the page would shrink to a third. */
const shown = () => {
if (kind !== 'phone') return screen.width;
return Math.min(screen.width, keptWidth < screen.width ? Math.max(PHONE_WIDTH, keptWidth) : PHONE_WIDTH);
};
const describe = () => screen && { kind, width: shown(), screen: [screen.width, screen.height] };
/** The bar above the page: how much taller its window is than the page, read with the page as tall as the screen.
* None on the password manager's page, which takes only the width and keeps its height under the bar. */
const measureBar = async () => {
addon = Boolean((await page.resize(screen.width, screen.height))?.addonPage);
if (addon) return null;
const over = pageWindows(view.display).filter(win => win.width === screen.width && win.height > screen.height).map(win => win.height - screen.height);
return over.length ? Math.min(...over) : null;
};
/** Sizes the page as the fit; resolves to whether the password manager's page shows. */
const size = async () => (addon = Boolean((await page.resize(fitted().width, fitted().height))?.addonPage));
/** Raises and focuses a window as tall as the screen and at least as wide as the fit (the browser's stops near 500).
* While a pop-up shows, none: a raise covers it and focus closes it. On a phone, the pop-up moves into the strip. */
const front = () => {
if (!screen || ended) return;
const popups = popupIds(view.display);
if (popups.length) {
if (kind === 'phone') popupsIntoStrip(view.display, popups, shown());
return;
}
const windows = pageWindows(view.display);
const fits = windows.filter(win => win.height === screen.height && win.width >= fitted().width);
const own = keptWindow(fits, seen, kept);
for (const win of windows) seen.add(win.id);
kept = own?.id ?? null;
keptWidth = kind === 'phone' ? own?.width ?? keptWidth : 0;
try { if (own) xdotool(view.display, 'windowraise', own.id, 'windowfocus', own.id); } catch { /* next poll */ }
};
return {
describe,
front,
/** True while a browser pop-up shows on the view's screen. */
popupOpen: () => !ended && popupOpen(view.display),
/** Fits the page as `next`, `phone` or `wide`, or as it was; resolves to the fit. */
fit: (next = kind) => inTurn(async () => {
if (ended || !page) return describe();
kind = next;
screen ??= screenSize(view.display);
// On the password manager's page a reading widens the page to the screen, and the fit narrows it again: so the
// bar waits there, and is read at the first fit whose answer comes from a site.
const waited = addon;
if (!waited) bar ??= await measureBar();
if (!await size() && waited && bar == null) {
bar = await measureBar();
await size();
}
if (addon) fitWindows(view.display, screen);
front();
return describe();
}),
/** Starts the screen source again when it has exited, on the browser's screen now; resolves to whether it did. */
revive: () => inTurn(async () => {
if (ended || alive(view.sourcePid)) return false;
const display = screenOf();
if (!display) throw new Error('the browser has no screen to show');
Object.assign(view, { display }, await startSource(display, view.dir));
return true;
}),
/** Shows `next`, or none, once `swap` has let the page shown before go. */
show: (next, swap = async () => {}) => inTurn(async () => {
if (ended) return;
await swap();
page = next;
}),
end: () => inTurn(async () => {
ended = true;
await endView(view, page);
}),
};
}
/** The pinned viewer's own file for a `/novnc/...` address, or null: only a script under its `core/` or `vendor/`. */
export function viewerFile(pathname, dir = viewerDir()) {
const inside = /^\/novnc\/((?:core|vendor)\/[\w./-]+\.js)$/.exec(pathname)?.[1];
if (!inside || inside.split('/').includes('..')) return null;
const file = join(dir, inside);
return statSync(file, { throwIfNoEntry: false })?.isFile() ? file : null;
}
/** A request's JSON body, or a status: 413 past the byte limit, 400 when it isn't JSON. */
export async function readBody(request) {
const chunks = [];
let size = 0;
for await (const chunk of request) {
size += chunk.length;
if (size <= BODY_MOST) chunks.push(chunk);
}
if (size > BODY_MOST) return 413;
try {
return JSON.parse(Buffer.concat(chunks).toString('utf8'));
} catch {
return 400;
}
}
/** Ends a route with a JSON reply, or an empty one. */
export function reply(response, status, body) {
const text = body ? JSON.stringify(body) : '';
response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'content-length': Buffer.byteLength(text) }).end(text);
}
/** The view's routes for `{note}`: `tabs()` adds a turn view's open turns, and `/show` runs `onShow(chat)`. `watch`
* hooks serve a watch link, which alone has a Hand back of its own. */
export function viewRoutes({ note }, { fitted = () => null, onFit = async () => null, onShow = async () => false, tabs = null, closesAt, watch = null } = {}) {
return async (pathname, request, response) => {
if (pathname === '/view') {
if (request.method !== 'GET') return reply(response, 405);
watch?.shown();
return reply(response, 200, { note, ...(watch ? { watch: true } : { control: 'turn' }), fit: fitted(), closesAt, ...tabs?.(), now: Date.now() });
}
if ((!watch && (pathname === '/watch' || WATCH_ACTIONS.has(pathname))) || (!tabs && pathname === '/show')) return reply(response, 404);
if (pathname === '/watch') return request.method === 'GET' ? reply(response, 200, { ...watch.info(), fit: fitted() }) : reply(response, 405);
if (request.method !== 'POST') return reply(response, 405);
if (watch && WATCH_ACTIONS.has(pathname)) {
const now = watch[pathname.slice(1)]();
return now ? reply(response, 200, now) : reply(response, 409);
}
// A body that is too big or not JSON names no chat and no fit.
const body = await readBody(request).then(read => (typeof read === 'object' ? read : null));
if (pathname === '/show') return (await onShow(body?.chat)) ? reply(response, 200, { ...tabs(), now: Date.now() }) : reply(response, 409);
const kind = body?.fit;
if (!FITS.includes(kind)) return reply(response, 400);
reply(response, 200, { fit: await onFit(kind) });
};
}