@myrtilleio/redline 0.1.0

package/src/server.js

@@ -0,0 +1,477 @@
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import tls from 'node:tls';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { watch } from 'node:fs';
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { buildClient } from './bundle.js';
+import { formatMarkdown } from './format.js';
+import { reportHtml, reportModel } from './report.js';
+import { CLIENT_PATH, injectScript } from './inject.js';
+import { ShotService, checkContext } from './shots.js';
+import { Store } from './store.js';
+
+const API = '/__redline/api';
+const FILES = '/__redline/files/';
+const MAX_BODY = 12 * 1024 * 1024; // room for pasted reference images
+const IGNORED_DIRS = new Set(['node_modules', '.git']);
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.xml': 'application/xml',
+  '.pdf': 'application/pdf',
+};
+
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'GET, POST, PATCH, DELETE, OPTIONS',
+  'access-control-allow-headers': 'content-type, x-redline-key',
+};
+
+// ---------------------------------------------------------------- access
+// Who may read and write feedback. You, on this machine, from the page Redline
+// serves: everything, no key (a request from another website, or through a
+// hostname that merely resolves here, doesn't count). Anyone else needs a key:
+// the owner key gives everything; the review key, carried by a shared Check link,
+// lets someone read the review and give verdicts, nothing more.
+
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|::1|::ffff:127\.\d+\.\d+\.\d+)$/;
+function localHostHeader(host) {
+  const name = String(host || '').replace(/:\d+$/, '').replace(/^\[|\]$/g, '').toLowerCase();
+  return name === 'localhost' || name.endsWith('.localhost') || LOOPBACK.test(name);
+}
+function sameKey(given, key) {
+  const a = Buffer.from(String(given)), b = Buffer.from(key);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/** 'owner' | 'review' | null for a request. */
+export function accessOf(req, url, keys) {
+  const given = req.headers['x-redline-key'] || url.searchParams.get('rk');
+  if (given && sameKey(given, keys.owner)) return 'owner';
+  if (given && sameKey(given, keys.review)) return 'review';
+  if (!LOOPBACK.test(req.socket.remoteAddress || '') || !localHostHeader(req.headers.host)) return null;
+  if (req.headers['sec-fetch-site'] === 'cross-site') return null;
+  const origin = req.headers.origin;
+  if (origin) {
+    try {
+      if (new URL(origin).host !== req.headers.host) return null;
+    } catch {
+      return null;
+    }
+  }
+  return 'owner';
+}
+
+// What a reviewer on a Check link may change: verdicts, not the review itself.
+const REVIEW_FIELDS = new Set(['accepted', 'rebaseline', 'sendBack', 'unguard', 'dynamic', 'status', 'draft', 'reply', 'target']);
+function reviewPatch(body) {
+  const out = {};
+  for (const [k, v] of Object.entries(body || {})) if (REVIEW_FIELDS.has(k)) out[k] = v;
+  if (body && body.sendBack === true && body.verdict === 'good') out.verdict = 'good';
+  return out;
+}
+
+function send(res, status, body, headers = {}) {
+  const buf = Buffer.isBuffer(body) ? body : Buffer.from(String(body));
+  res.writeHead(status, { 'content-length': buf.length, 'cache-control': 'no-store', ...headers });
+  res.end(buf);
+}
+
+function json(res, status, data) {
+  send(res, status, JSON.stringify(data), { 'content-type': 'application/json; charset=utf-8', ...CORS });
+}
+
+function readBody(req) {
+  return new Promise((ok, fail) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > MAX_BODY) {
+        fail(Object.assign(new Error('body too large'), { status: 413 }));
+        req.destroy();
+      } else chunks.push(c);
+    });
+    req.on('end', () => {
+      try {
+        ok(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+      } catch {
+        fail(Object.assign(new Error('invalid JSON'), { status: 400 }));
+      }
+    });
+    req.on('error', fail);
+  });
+}
+
+/**
+ * Let the injected overlay run under the site's Content-Security-Policy: allow its
+ * script and its API/event-stream requests on the proxy's own origin. Policies
+ * using 'strict-dynamic' ignore host sources, so those get a nonce instead (they
+ * already rely on nonces, so a new one doesn't disable 'unsafe-inline').
+ */
+export function patchCsp(header, nonce) {
+  return header
+    .split(',')
+    .map((policy) => {
+      const dirs = policy.split(';').map((d) => d.trim()).filter(Boolean);
+      const find = (name) => dirs.findIndex((d) => d.split(/\s+/)[0].toLowerCase() === name);
+      const allow = (name, token) => {
+        let i = find(name);
+        if (i < 0) {
+          const fallback = find('default-src');
+          if (fallback < 0) return;
+          dirs.push(name + dirs[fallback].slice('default-src'.length));
+          i = dirs.length - 1;
+        }
+        if (/'none'/.test(dirs[i])) dirs[i] = name;
+        dirs[i] += ' ' + token;
+      };
+      for (const name of ['script-src', 'script-src-elem']) {
+        if (name === 'script-src-elem' && find(name) < 0) continue;
+        const i = find(name) >= 0 ? find(name) : find('default-src');
+        const strict = i >= 0 && /'strict-dynamic'/.test(dirs[i]);
+        allow(name, strict ? `'nonce-${nonce}'` : "'self'");
+      }
+      allow('connect-src', "'self'");
+      // Screenshots and reference images; skip when images are already allowed from anywhere.
+      const img = find('img-src') >= 0 ? dirs[find('img-src')] : find('default-src') >= 0 ? dirs[find('default-src')] : null;
+      if (img !== null && !/\s\*(\s|$)/.test(img)) allow('img-src', "'self' data: blob:");
+      return dirs.join('; ');
+    })
+    .join(', ');
+}
+
+function escapeHtml(s) {
+  return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+}
+
+/**
+ * Create the Redline server.
+ * - `root`: serve a static site directory, injecting the overlay and live-reloading on change; or
+ * - `target`: reverse-proxy a running dev server (e.g. http://localhost:5173), injecting the overlay.
+ * Feedback is stored in `storeDir` (feedback.json + FEEDBACK.md).
+ */
+export function createRedlineServer({ root, target, storeDir, log = () => {}, shots: wantShots = true, keys: givenKeys, demo = false }) {
+  if (!root === !target) throw new Error('pass exactly one of root or target');
+  // New keys every run unless given: a shared link stops working when the review does.
+  const keys = { owner: randomBytes(12).toString('base64url'), review: randomBytes(12).toString('base64url'), ...(givenKeys || {}) };
+  const store = new Store(storeDir);
+  let server;
+  const shots = new ShotService({
+    store,
+    log,
+    baseUrl: () => `http://127.0.0.1:${server.address().port}`,
+    onShot: (key, a) => a && broadcast('annotations', { page: a.page }),
+    ...(wantShots ? {} : { chrome: null }),
+  });
+  const clients = new Set();
+  const watchers = [];
+  const upstream = target ? new URL(target) : null;
+  const siteRoot = root ? resolve(root) : null;
+
+  function broadcast(event, data = {}) {
+    const msg = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of clients) res.write(msg);
+  }
+
+  function debounce(fn, ms) {
+    let t;
+    return (...args) => {
+      clearTimeout(t);
+      t = setTimeout(() => fn(...args), ms);
+    };
+  }
+
+  async function api(req, res, url) {
+    const rest = url.pathname.slice(API.length);
+    const id = rest.startsWith('/annotations/') ? decodeURIComponent(rest.slice('/annotations/'.length)) : null;
+    const role = accessOf(req, url, keys);
+    if (!role) return json(res, 401, { error: 'Redline: this needs a key. Open the link you were given, or ask for a new one.' });
+    if (role === 'review') {
+      const allowed = req.method === 'GET' || (id && req.method === 'PATCH') || (rest === '/send' && req.method === 'POST') ||
+        (rest.startsWith('/rounds/') && req.method === 'PATCH');
+      if (!allowed) return json(res, 403, { error: 'Redline: a Check link can give verdicts, not change the review' });
+    }
+
+    if (rest === '/events' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive', ...CORS });
+      res.write(`event: hello\ndata: ${JSON.stringify({ mode: root ? 'serve' : 'proxy' })}\n\n`);
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    if (rest === '/annotations' && req.method === 'GET') {
+      return json(res, 200, await store.list(url.searchParams.get('page')));
+    }
+    if (rest === '/annotations' && req.method === 'POST') {
+      const a = await store.create(await readBody(req));
+      broadcast('annotations', { page: a.page });
+      log(`+ ${a.verdict} ${a.kind} on ${a.page}${a.comment ? `: ${a.comment.slice(0, 60)}` : ''}`);
+      return json(res, 201, a);
+    }
+    if (id && req.method === 'PATCH') {
+      const body = await readBody(req);
+      const a = await store.update(id, role === 'review' ? reviewPatch(body) : body);
+      if (!a) return json(res, 404, { error: 'not found' });
+      broadcast('annotations', { page: a.page });
+      return json(res, 200, a);
+    }
+    if (id && req.method === 'DELETE') {
+      const ok = await store.remove(id);
+      broadcast('annotations', {});
+      return json(res, ok ? 200 : 404, { ok });
+    }
+    if (rest === '/assets' && req.method === 'POST') {
+      const { dataUrl } = await readBody(req);
+      return json(res, 201, { path: await store.saveAsset(dataUrl) });
+    }
+    if (rest === '/info' && req.method === 'GET') {
+      // The owner gets the review key, to build Check links with.
+      return json(res, 200, { mode: root ? 'serve' : 'proxy', shots: shots.available, role, demo, ...(role === 'owner' ? { reviewKey: keys.review } : {}) });
+    }
+    // Turn-taking: send the drafts as a round; read the rounds; answer a round's report.
+    if (rest === '/send' && req.method === 'POST') {
+      const round = await store.send();
+      if (round) log(`→ round ${round.n} sent to the agent (${round.count} item${round.count === 1 ? '' : 's'})`);
+      return json(res, round ? 201 : 200, round || { nothing: true });
+    }
+    if (rest === '/rounds' && req.method === 'GET') return json(res, 200, await store.rounds());
+    if (rest.startsWith('/rounds/') && req.method === 'PATCH') {
+      return json(res, 200, await store.answerRound(rest.slice('/rounds/'.length), await readBody(req)));
+    }
+    // The round as one shareable page (the ⋯ menu opens it).
+    if (rest === '/report' && req.method === 'GET') {
+      const model = reportModel(await store.all(), await store.rounds(), url.searchParams.get('round'));
+      return send(res, 200, await reportHtml(model, { storeDir }), { 'content-type': 'text/html; charset=utf-8' });
+    }
+    if (rest === '/prompt' && req.method === 'GET') {
+      const page = url.searchParams.get('page');
+      const list = await store.list(page);
+      const md = formatMarkdown(list, { cli: true, includeResolved: url.searchParams.has('resolved'), rounds: (await store.rounds()).rounds, taste: await store.taste() });
+      return send(res, 200, md, { 'content-type': 'text/markdown; charset=utf-8', ...CORS });
+    }
+    return json(res, 404, { error: 'unknown endpoint' });
+  }
+
+  async function serveStatic(req, res, url) {
+    let pathname;
+    try {
+      pathname = decodeURIComponent(url.pathname);
+    } catch {
+      return send(res, 400, 'bad path');
+    }
+    let file = resolve(siteRoot, '.' + pathname);
+    if (file !== siteRoot && !file.startsWith(siteRoot + sep)) return send(res, 403, 'forbidden');
+    if (relative(siteRoot, file).split(sep).some((p) => p.startsWith('.') && p.length > 1)) return send(res, 404, 'not found');
+
+    let info = await stat(file).catch(() => null);
+    if (info?.isDirectory()) {
+      if (!pathname.endsWith('/')) return send(res, 301, '', { location: url.pathname + '/' + url.search });
+      const index = join(file, 'index.html');
+      const indexInfo = await stat(index).catch(() => null);
+      if (!indexInfo) return listing(res, file, pathname);
+      file = index;
+      info = indexInfo;
+    }
+    if (!info && !extname(file)) {
+      const html = file + '.html';
+      info = await stat(html).catch(() => null);
+      if (info) file = html;
+    }
+    if (!info) return send(res, 404, injectScript('<!doctype html><title>Not found</title><h1>404</h1>'), { 'content-type': MIME['.html'] });
+
+    const type = MIME[extname(file).toLowerCase()] || 'application/octet-stream';
+    let body = await readFile(file);
+    if (type.startsWith('text/html')) body = Buffer.from(injectScript(body.toString('utf8')));
+    send(res, 200, req.method === 'HEAD' ? '' : body, { 'content-type': type });
+  }
+
+  async function listing(res, dir, pathname) {
+    const entries = (await readdir(dir, { withFileTypes: true })).filter((e) => !e.name.startsWith('.') && !IGNORED_DIRS.has(e.name));
+    entries.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+    const items = entries
+      .map((e) => {
+        const name = e.name + (e.isDirectory() ? '/' : '');
+        return `<li><a href="${escapeHtml(encodeURI(pathname + name))}">${escapeHtml(name)}</a></li>`;
+      })
+      .join('');
+    const html = `<!doctype html><meta charset="utf-8"><title>${escapeHtml(pathname)}</title>
+<style>body{font:15px/1.6 system-ui,sans-serif;max-width:640px;margin:48px auto;padding:0 16px}a{color:#2563eb}</style>
+<h1>Index of ${escapeHtml(pathname)}</h1><ul>${items || '<li>(empty)</li>'}</ul>`;
+    send(res, 200, injectScript(html), { 'content-type': MIME['.html'] });
+  }
+
+  function proxy(req, res) {
+    const lib = upstream.protocol === 'https:' ? https : http;
+    const headers = { ...req.headers, host: upstream.host, 'accept-encoding': 'identity' };
+    const up = lib.request(
+      { protocol: upstream.protocol, hostname: upstream.hostname, port: upstream.port, method: req.method, path: req.url, headers },
+      (upRes) => {
+        const out = { ...upRes.headers };
+        if (typeof out.location === 'string' && out.location.startsWith(upstream.origin)) {
+          out.location = out.location.slice(upstream.origin.length) || '/';
+        }
+        const isHtml = String(out['content-type'] || '').includes('text/html');
+        if (!isHtml || req.method === 'HEAD') {
+          res.writeHead(upRes.statusCode, out);
+          return upRes.pipe(res);
+        }
+        const chunks = [];
+        upRes.on('data', (c) => chunks.push(c));
+        upRes.on('error', () => res.destroy());
+        upRes.on('end', () => {
+          if (res.headersSent || !upRes.complete) return res.destroy();
+          const nonce = randomBytes(12).toString('base64');
+          for (const name of ['content-security-policy', 'content-security-policy-report-only']) {
+            if (out[name]) out[name] = [].concat(out[name]).map((v) => patchCsp(v, nonce));
+          }
+          const tag = `<script src="${CLIENT_PATH}" defer data-redline nonce="${nonce}"></script>`;
+          const body = Buffer.from(injectScript(Buffer.concat(chunks).toString('utf8'), tag));
+          delete out['content-encoding'];
+          delete out['transfer-encoding'];
+          out['content-length'] = body.length;
+          res.writeHead(upRes.statusCode, out);
+          res.end(body);
+        });
+      },
+    );
+    up.on('error', (err) => {
+      if (res.headersSent) return res.destroy();
+      send(res, 502, `Redline could not reach ${upstream.origin}: ${err.message}`, { 'content-type': 'text/plain; charset=utf-8' });
+    });
+    req.pipe(up);
+  }
+
+  // Forward WebSocket upgrades (dev-server HMR) untouched.
+  function proxyUpgrade(req, socket, head) {
+    const port = upstream.port || (upstream.protocol === 'https:' ? 443 : 80);
+    const up =
+      upstream.protocol === 'https:'
+        ? tls.connect({ host: upstream.hostname, port, servername: upstream.hostname })
+        : net.connect({ host: upstream.hostname, port });
+    const ready = upstream.protocol === 'https:' ? 'secureConnect' : 'connect';
+    up.once(ready, () => {
+      const lines = [`${req.method} ${req.url} HTTP/1.1`];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        const name = req.rawHeaders[i];
+        lines.push(`${name}: ${name.toLowerCase() === 'host' ? upstream.host : req.rawHeaders[i + 1]}`);
+      }
+      up.write(lines.join('\r\n') + '\r\n\r\n');
+      if (head?.length) up.write(head);
+      up.pipe(socket);
+      socket.pipe(up);
+    });
+    up.on('error', () => socket.destroy());
+    socket.on('error', () => up.destroy());
+  }
+
+  // Uploaded references and screenshots, from the store's assets/ and shots/ folders.
+  async function serveStoreFile(res, url) {
+    const rel = decodeURIComponent(url.pathname.slice(FILES.length));
+    if (!/^(assets|shots)\/[\w.-]{1,80}$/.test(rel)) return send(res, 404, 'not found');
+    const body = await readFile(join(storeDir, rel)).catch(() => null);
+    if (!body) return send(res, 404, 'not found');
+    send(res, 200, body, { 'content-type': MIME[extname(rel).toLowerCase()] || 'application/octet-stream', ...CORS });
+  }
+
+  server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    try {
+      if (url.pathname.startsWith(FILES)) {
+        if (!accessOf(req, url, keys)) return send(res, 401, 'this needs a key');
+        return await serveStoreFile(res, url);
+      }
+      if (req.method === 'OPTIONS' && url.pathname.startsWith('/__redline/')) return send(res, 204, '', CORS);
+      if (url.pathname === CLIENT_PATH) {
+        const clientJs = buildClient(); // ~1ms; rebuilt per request so edits to the overlay show up on reload
+        return send(res, 200, clientJs, { 'content-type': MIME['.js'], ...CORS });
+      }
+      if (url.pathname.startsWith(API + '/')) return await api(req, res, url);
+      if (upstream) return proxy(req, res);
+      if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'method not allowed');
+      return await serveStatic(req, res, url);
+    } catch (err) {
+      log(`error: ${err.message}`);
+      if (!res.headersSent) json(res, err.status || 500, { error: err.message });
+      else res.destroy();
+    }
+  });
+
+  if (upstream) server.on('upgrade', proxyUpgrade);
+
+  server.on('listening', async () => {
+    await mkdir(storeDir, { recursive: true });
+    const onStore = debounce(async () => {
+      broadcast('annotations', {});
+      shots.reconcile(await store.all().catch(() => []), checkContext(await store.rounds()));
+    }, 80);
+    shots.reconcile(await store.all().catch(() => []), checkContext(await store.rounds()));
+    watchers.push(watch(storeDir, onStore));
+    if (siteRoot) {
+      const absStore = resolve(storeDir);
+      const onSite = debounce((file) => {
+        log(`changed ${file} → reloading browsers`);
+        broadcast('reload', { file });
+      }, 120);
+      watchers.push(
+        watch(siteRoot, { recursive: true }, (_event, name) => {
+          if (!name) return;
+          const abs = resolve(siteRoot, name);
+          if (abs === absStore || abs.startsWith(absStore + sep)) return;
+          if (name.split(sep).some((p) => IGNORED_DIRS.has(p) || (p.startsWith('.') && p.length > 1))) return;
+          onSite(name);
+        }),
+      );
+    }
+    // Keep proxies and load balancers from closing idle event streams.
+    const ping = setInterval(() => {
+      for (const res of clients) res.write(': ping\n\n');
+    }, 25000);
+    ping.unref();
+    watchers.push({ close: () => clearInterval(ping) });
+  });
+
+  server.on('close', () => {
+    shots.close();
+    for (const w of watchers) w.close();
+    for (const res of clients) res.end();
+  });
+
+  // Let server.close() finish even while browsers hold event streams open.
+  const close = server.close.bind(server);
+  server.close = (cb) => {
+    for (const res of clients) res.end();
+    clients.clear();
+    server.closeAllConnections?.();
+    return close(cb);
+  };
+
+  server.store = store;
+  server.shots = shots;
+  server.keys = keys;
+  return server;
+}