diffsplain 0.5.0 → 0.6.0

package/scripts/presenter-runtime.mjs

@@ -0,0 +1,148 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function agentRunNeeded(
+  fingerprint,
+  { activeFingerprint, completedFingerprint, failedFingerprint } = {},
+) {
+  return Boolean(
+    fingerprint &&
+      fingerprint !== activeFingerprint &&
+      fingerprint !== completedFingerprint &&
+      fingerprint !== failedFingerprint,
+  );
+}
+
+function agentRunStopped({ code, error, signal }) {
+  return Boolean(error || code || signal);
+}
+
+export function agentRunCompleted({ code, error, signal, superseded }) {
+  if (superseded) return false;
+  return !agentRunStopped({ code, error, signal });
+}
+
+export function agentRunSuperseded(
+  queuedFingerprint,
+  finishedFingerprint,
+) {
+  return Boolean(
+    queuedFingerprint && queuedFingerprint !== finishedFingerprint,
+  );
+}
+
+export function agentFallbackRecordNeeded({
+  closing,
+  queuedFingerprint,
+  error,
+  signal,
+}) {
+  if (closing) return false;
+  if (queuedFingerprint) return false;
+  return Boolean(error || signal);
+}
+
+export function agentRunFailed({
+  closing,
+  code,
+  error,
+  signal,
+  superseded,
+}) {
+  if (closing) return false;
+  if (superseded) return false;
+  return agentRunStopped({ code, error, signal });
+}
+
+export function failedAgentRunForFingerprint(
+  failedFingerprint,
+  observedFingerprint,
+) {
+  if (!failedFingerprint || !observedFingerprint) return failedFingerprint;
+  return failedFingerprint === observedFingerprint
+    ? failedFingerprint
+    : undefined;
+}
+
+export function nextAgentFingerprint({
+  queuedFingerprint,
+  observedFingerprint,
+  finishedFingerprint,
+}) {
+  const latest = queuedFingerprint || observedFingerprint;
+  if (!latest || latest === finishedFingerprint) return undefined;
+  return latest;
+}
+
+export function browserCommand({ url, browser, platform = process.platform }) {
+  if (browser) return { command: browser, args: [url] };
+  if (platform === 'darwin') return { command: 'open', args: [url] };
+  if (platform === 'win32') {
+    return { command: 'cmd.exe', args: ['/d', '/s', '/c', 'start', '', url] };
+  }
+  return { command: 'xdg-open', args: [url] };
+}
+
+export function openBrowser(
+  url,
+  {
+    browser = process.env.BROWSER,
+    platform = process.platform,
+    spawnProcess = spawn,
+    onError = () => {},
+  } = {},
+) {
+  try {
+    const { command, args } = browserCommand({ url, browser, platform });
+    const opener = spawnProcess(command, args, { detached: true, stdio: 'ignore' });
+    opener.once('error', onError);
+    opener.unref();
+    return opener;
+  } catch (error) {
+    onError(error);
+    return undefined;
+  }
+}
+
+function builtAssetsReady({ root, exists = existsSync }) {
+  const dist = join(root, 'dist');
+  return exists(join(dist, 'index.html')) && exists(join(dist, 'assets'));
+}
+
+function npmCommand(platform) {
+  return platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function buildAssets(runtime) {
+  const result = runtime.run(npmCommand(runtime.platform), ['run', 'build'], {
+    cwd: runtime.root,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    throw new Error(`Could not build the local page: ${result.error.message}`);
+  }
+  if (result.status === 0) return;
+  const status = Number.isInteger(result.status) ? Number(result.status) : 1;
+  const error = new Error(
+    `Could not build the local page: npm run build exited with ${status}.`,
+  );
+  error.exitCode = status;
+  throw error;
+}
+
+export function ensureBuiltAssets(options) {
+  const runtime = {
+    exists: existsSync,
+    run: spawnSync,
+    platform: process.platform,
+    ...options,
+  };
+  if (builtAssetsReady({ root: runtime.root, exists: runtime.exists })) return false;
+
+  buildAssets(runtime);
+  if (!builtAssetsReady({ root: runtime.root, exists: runtime.exists })) {
+    throw new Error('Could not build the local page: built assets are still missing.');
+  }
+  return true;
+}

package/scripts/serve-built.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { watchFile, unwatchFile } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
-import { Readable } from 'node:stream';
+import { createServer } from 'node:http';
 import { dirname, extname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -24,9 +24,18 @@ function option(name, fallback) {
 const output = resolve(option('--output', resolve(root, '.cache/diff-data.json')));
 const project = option('--project', '');
 const portValue = option('--port', '2299');
+const host = option('--host', 'localhost').replace(/^\[|\]$/g, '');
+const access = option('--access', randomBytes(32).toString('base64url'));
+const previousAccess = option('--previous-access', '');
 if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
   throw new Error('--port must be a number from 0 to 65535');
 }
+if (!/^[A-Za-z0-9_-]{32,}$/.test(access)) {
+  throw new Error('--access must be an unguessable URL-safe value');
+}
+if (previousAccess && !/^[A-Za-z0-9_-]{32,}$/.test(previousAccess)) {
+  throw new Error('--previous-access must be an unguessable URL-safe value');
+}
 const incrementPort =
   rawArgs.includes('--increment-port') || !rawArgs.includes('--port');
 
@@ -41,22 +50,65 @@ const contentTypes = {
   '.woff2': 'font/woff2',
 };
 
+const restrictiveHeaders = {
+  'content-security-policy':
+    "base-uri 'none'; connect-src 'self'; default-src 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; style-src 'self' 'unsafe-inline'",
+  'cross-origin-opener-policy': 'same-origin',
+  'cross-origin-resource-policy': 'same-origin',
+  'permissions-policy': 'geolocation=(), microphone=(), camera=()',
+  'referrer-policy': 'no-referrer',
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': 'DENY',
+};
+
+function webResponse(body, { status = 200, headers = {} } = {}) {
+  return new Response(body, {
+    status,
+    headers: { ...restrictiveHeaders, ...headers },
+  });
+}
+
+function clientError() {
+  return webResponse('Bad request', { status: 400 });
+}
+
 function notFound() {
-  return new Response('Not found', { status: 404 });
+  return webResponse('Not found', { status: 404 });
+}
+
+function isLoopback(address) {
+  const normalized = address.replace(/^\[|\]$/g, '').toLowerCase();
+  return (
+    normalized === 'localhost' ||
+    normalized === '::1' ||
+    normalized === '::ffff:127.0.0.1' ||
+    /^127(?:\.\d{1,3}){3}$/.test(normalized)
+  );
+}
+
+function normalizedAddress(address) {
+  return address.replace(/^\[|\]$/g, '').toLowerCase();
+}
+
+function cacheControl(file) {
+  const extension = extname(file).toLowerCase();
+  if (extension === '.html') return 'no-cache';
+  if (/[-_][A-Za-z0-9_-]{8,}\.(?:css|js|woff2?)$/.test(file)) {
+    return 'public, max-age=31536000, immutable';
+  }
+  return 'no-cache';
 }
 
 async function fileResponse(file, { live = false } = {}) {
   try {
     const info = await stat(file);
     if (!info.isFile()) return notFound();
-    return new Response(await readFile(file), {
+    return webResponse(await readFile(file), {
       headers: {
+        'cache-control': live ? 'no-store' : cacheControl(file),
         'content-type':
           contentTypes[extname(file).toLowerCase()] ||
           'application/octet-stream',
-        'cache-control': live
-          ? 'no-store'
-          : 'public, max-age=31536000, immutable',
       },
     });
   } catch {
@@ -64,103 +116,321 @@ async function fileResponse(file, { live = false } = {}) {
   }
 }
 
-async function fetchAsset(request) {
-  const url = new URL(request.url);
-  if (url.pathname === '/diff-data.json') {
-    return fileResponse(output, { live: true });
+function decodeRequestPath(rawPath) {
+  try {
+    return decodeURIComponent(rawPath);
+  } catch {
+    return undefined;
   }
+}
 
-  let pathname;
+function unsafeRequestPath(rawPath, decodedPath) {
+  if (!rawPath.startsWith('/')) return true;
+  if (authorityPath(rawPath, decodedPath)) return true;
+  if (decodedPath.includes('\\')) return true;
+  return decodedPath.split('/').includes('..');
+}
+
+function authorityPath(rawPath, decodedPath) {
+  return rawPath.startsWith('//') || decodedPath.startsWith('//');
+}
+
+function parseUrl(raw) {
   try {
-    pathname = decodeURIComponent(url.pathname);
+    return new URL(raw, 'http://localhost');
   } catch {
-    return notFound();
+    return undefined;
   }
+}
+
+function parseRequestUrl(request) {
+  const raw = request.url || '/';
+  const rawPath = raw.split(/[?#]/, 1)[0];
+  const decodedPath = decodeRequestPath(rawPath);
+  if (decodedPath === undefined) return undefined;
+  if (unsafeRequestPath(rawPath, decodedPath)) return undefined;
+  return parseUrl(raw);
+}
+
+function parseHttpHost(value) {
+  if (!value) return undefined;
+  try {
+    return new URL(`http://${value}`);
+  } catch {
+    return undefined;
+  }
+}
+
+function serverPort(url) {
+  if (url.port) return url.port;
+  return readyState?.port === 80 ? '80' : '';
+}
+
+function plainHost(url) {
+  return ![
+    url.username,
+    url.password,
+    url.pathname !== '/',
+    url.search,
+    url.hash,
+  ].some(Boolean);
+}
+
+function matchesServerAddress(candidate, localAddress) {
+  const local = normalizedAddress(localAddress);
+  const accepted = new Set([normalizedAddress(host), local]);
+  if (accepted.has(candidate)) return true;
+  return isLoopback(candidate) && isLoopback(local);
+}
+
+function validHost(value, localAddress) {
+  const url = parseHttpHost(value);
+  if (!url) return false;
+  if (!plainHost(url)) return false;
+  if (serverPort(url) !== String(readyState.port)) return false;
+  return matchesServerAddress(normalizedAddress(url.hostname), localAddress);
+}
+
+function parseOriginPair(value, requestHost) {
+  if (value === 'null') return undefined;
+  try {
+    return {
+      origin: new URL(value),
+      requestUrl: new URL(`http://${requestHost}`),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function matchingOrigin({ origin, requestUrl }) {
+  const plainOrigin = ![
+    origin.protocol !== 'http:',
+    origin.username,
+    origin.password,
+    origin.pathname !== '/',
+    origin.search,
+    origin.hash,
+  ].some(Boolean);
+  if (!plainOrigin) return false;
+  if (
+    normalizedAddress(origin.hostname) !==
+    normalizedAddress(requestUrl.hostname)
+  ) {
+    return false;
+  }
+  return serverPort(origin) === serverPort(requestUrl);
+}
+
+function validOrigin(value, requestHost, localAddress) {
+  if (!value) return true;
+  const pair = parseOriginPair(value, requestHost);
+  if (!pair) return false;
+  if (!matchingOrigin(pair)) return false;
+  return validHost(pair.origin.host, localAddress);
+}
+
+function validAccess(value, { allowPrevious = false } = {}) {
+  if (matchingAccess(value, access)) return true;
+  return (
+    allowPrevious &&
+    Boolean(previousAccess) &&
+    matchingAccess(value, previousAccess)
+  );
+}
+
+function matchingAccess(value, expectedValue) {
+  const received = Buffer.from(value || '');
+  const expected = Buffer.from(expectedValue);
+  return received.length === expected.length && timingSafeEqual(received, expected);
+}
+
+async function fetchAsset(url) {
+  if (url.pathname === '/diff-data.json') {
+    return fileResponse(output, { live: true });
+  }
+  const pathname = decodeURIComponent(url.pathname);
   const file = resolve(
     clientRoot,
     pathname === '/' ? 'index.html' : `.${pathname}`,
   );
   if (file !== clientRoot && !file.startsWith(`${clientRoot}${sep}`)) {
-    return notFound();
+    return clientError();
   }
   return fileResponse(file);
 }
 
-function nodeRequest(request) {
-  const host = request.headers.host || 'localhost';
-  const init = {
-    method: request.method,
-    headers: request.headers,
-  };
-  if (request.method !== 'GET' && request.method !== 'HEAD') {
-    init.body = Readable.toWeb(request);
-    init.duplex = 'half';
-  }
-  return new Request(`http://${host}${request.url}`, init);
+function jsonResponse(value, status = 200) {
+  return webResponse(JSON.stringify(value), {
+    status,
+    headers: {
+      'cache-control': 'no-store',
+      'content-type': 'application/json; charset=utf-8',
+    },
+  });
 }
 
-async function send(nodeResponse, response) {
-  nodeResponse.writeHead(response.status, Object.fromEntries(response.headers));
-  if (!response.body) {
+async function send(nodeResponse, webResponse) {
+  nodeResponse.writeHead(
+    webResponse.status,
+    Object.fromEntries(webResponse.headers),
+  );
+  if (!webResponse.body) {
     nodeResponse.end();
     return;
   }
-  Readable.fromWeb(response.body).pipe(nodeResponse);
+  nodeResponse.end(Buffer.from(await webResponse.arrayBuffer()));
+}
+
+const eventClients = new Set();
+let selectedPort = Number(portValue);
+let readyState;
+let closing = false;
+
+function requestAuthorityError(request) {
+  const localAddress = request.socket.localAddress || '';
+  if (!validHost(request.headers.host, localAddress)) {
+    return clientError();
+  }
+  if (!validOrigin(request.headers.origin, request.headers.host, localAddress)) {
+    return webResponse('Forbidden', { status: 403 });
+  }
+  return undefined;
+}
+
+function requestContext(request) {
+  const url = parseRequestUrl(request);
+  if (!url) return { error: clientError() };
+  const authorityError = requestAuthorityError(request);
+  if (authorityError) return { error: authorityError };
+  if (!['GET', 'HEAD'].includes(request.method)) {
+    return { error: webResponse('Method not allowed', { status: 405 }) };
+  }
+  return { url };
+}
+
+function forcedHandlerFailure(url) {
+  return (
+    process.env.DIFFSPLAIN_TEST_HANDLER_FAILURE &&
+    url.pathname === '/__test/fail'
+  );
+}
+
+async function sendEvents(response, url) {
+  if (
+    !validAccess(url.searchParams.get('access'), { allowPrevious: true })
+  ) {
+    await send(response, webResponse('Forbidden', { status: 403 }));
+    return;
+  }
+  response.writeHead(200, {
+    ...restrictiveHeaders,
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+  });
+  response.write('retry: 250\nevent: ready\ndata: {}\n\n');
+  response.write(`event: access\ndata: ${access}\n\n`);
+  eventClients.add(response);
+  const requestProject = url.searchParams.get('project');
+  if (project && requestProject === project) {
+    console.log('Diffsplain tab: connected');
+  }
+  response.once('close', () => eventClients.delete(response));
+}
+
+async function routeResponse(url) {
+  if (url.pathname === '/health') return jsonResponse(readyState);
+  if (url.pathname === '/diff-data.json') {
+    if (!validAccess(url.searchParams.get('access'))) {
+      return webResponse('Forbidden', { status: 403 });
+    }
+  }
+  return fetchAsset(url);
 }
 
-const server = createServer(async (request, response) => {
+async function handleRequest(request, response) {
+  const context = requestContext(request);
+  if (context.error) {
+    await send(response, context.error);
+    return;
+  }
+  if (forcedHandlerFailure(context.url)) {
+    throw new Error('forced request handler failure');
+  }
+  if (context.url.pathname === '/events') {
+    await sendEvents(response, context.url);
+    return;
+  }
+  await send(response, await routeResponse(context.url));
+}
+
+async function containHandlerFailure(response) {
   try {
-    const webRequest = nodeRequest(request);
-    if (new URL(webRequest.url).pathname === '/events') {
-      response.writeHead(200, {
-        'content-type': 'text/event-stream',
-        'cache-control': 'no-store',
-        connection: 'keep-alive',
-      });
-      response.write('retry: 250\nevent: ready\ndata: {}\n\n');
-      eventClients.add(response);
-      const requestProject = new URL(webRequest.url).searchParams.get('project');
-      if (project && requestProject === project) {
-        console.log('Diffsplain tab: connected');
-      }
-      request.once('close', () => eventClients.delete(response));
+    if (response.headersSent) {
+      response.end();
       return;
     }
-    await send(response, await fetchAsset(webRequest));
-  } catch (error) {
-    console.error(error);
-    response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
-    response.end('Diffsplain could not load this page.');
+    await send(
+      response,
+      webResponse('Internal server error', { status: 500 }),
+    );
+  } catch {
+    response.destroy();
   }
+}
+
+const server = createServer((request, response) => {
+  void handleRequest(request, response).catch(() =>
+    containHandlerFailure(response),
+  );
 });
 
-const eventClients = new Set();
 watchFile(output, { interval: 100 }, (current, previous) => {
-  if (
-    current.mtimeMs === previous.mtimeMs &&
-    current.size === previous.size
-  ) {
+  if (current.mtimeMs === previous.mtimeMs && current.size === previous.size) {
     return;
   }
   for (const client of eventClients) {
-    client.write('event: update\ndata: {}\n\n');
+    if (!client.destroyed) client.write('event: update\ndata: {}\n\n');
   }
 });
 
-let selectedPort = Number(portValue);
+function urlFor(address, port) {
+  const formattedAddress = address.includes(':') ? `[${address}]` : address;
+  return `http://${formattedAddress}:${port}`;
+}
 
 function listen() {
-  server.listen(selectedPort, 'localhost');
+  server.listen(selectedPort, host);
 }
 
 server.on('listening', () => {
+  if (closing) {
+    server.close();
+    return;
+  }
   const address = server.address();
+  const readyAddress =
+    address && typeof address === 'object' ? address.address : host;
   const readyPort =
     address && typeof address === 'object' ? address.port : selectedPort;
-  const projectHash = project
-    ? `#project=${encodeURIComponent(project)}`
-    : '';
-  console.log(`Diffsplain: http://localhost:${readyPort}${projectHash}`);
+  const url = urlFor(host, readyPort);
+  const fragment = new URLSearchParams({
+    ...(project ? { project } : {}),
+    access,
+  });
+  readyState = {
+    status: 'ok',
+    address: readyAddress,
+    port: readyPort,
+  };
+  if (!isLoopback(readyAddress)) {
+    console.warn(
+      `Warning: Diffsplain is listening on ${readyAddress}. Review data still requires the per-run access value.`,
+    );
+  }
+  console.log(`Diffsplain: ${url}#${fragment}`);
+  console.log(JSON.stringify({ event: 'ready', ...readyState, url, access }));
 });
 
 server.on('error', (error) => {
@@ -174,23 +444,25 @@ server.on('error', (error) => {
     listen();
     return;
   }
-  console.error(`Could not start Diffsplain: ${error.message}`);
-  process.exitCode = 1;
+  const message =
+    error.code === 'EADDRINUSE'
+      ? `port ${selectedPort} is already in use`
+      : error.message;
+  console.error(`Could not start Diffsplain: ${message}`);
+  close(1);
 });
 
 listen();
 
-let closing = false;
-function close() {
+function close(exitCode = 0) {
   if (closing) return;
   closing = true;
+  process.exitCode = exitCode;
   unwatchFile(output);
   for (const client of eventClients) client.end();
   eventClients.clear();
-  server.close(() => {
-    process.exitCode = 0;
-  });
+  if (server.listening) server.close();
 }
 
-process.on('SIGINT', close);
-process.on('SIGTERM', close);
+process.on('SIGINT', () => close());
+process.on('SIGTERM', () => close());