@hncode/hncode 0.3.6 → 0.4.1

package/src/web-auth.js

@@ -0,0 +1,98 @@
+// Authentication for the local web UI.
+//
+// THREAT MODEL, stated plainly because it decides every choice here: the server
+// binds to a local address by default and serves one user's coding session — the
+// transcript, the file contents it read, and the ability to RUN COMMANDS as that
+// user. So the bar is not "keep out a determined attacker"; it is:
+//   * a page the user visits in another tab must not be able to talk to it
+//     (same-origin rules do not apply to `fetch` from a random site without CORS,
+//     but a form POST or a `<img>`/websocket still reaches it),
+//   * another user on the same machine must not read the transcript,
+//   * a leaked URL pasted into a chat must not be enough on its own.
+//
+// What that buys:
+//   * a 256-bit TOKEN, generated per process, required on every request;
+//   * constant-time comparison, so a token cannot be guessed byte by byte;
+//   * a same-origin check on state-changing requests (Origin/Referer must match
+//     the bound host), which is the standard defence against a cross-site POST;
+//   * HttpOnly + SameSite=Strict session cookie after a one-time token exchange,
+//     so the token does not have to sit in the page's JS or in a URL.
+//
+// What it deliberately does NOT do: TLS (the transport is loopback), user
+// accounts, or rate limiting beyond a small login delay. Binding to a non-loopback
+// address is allowed (/web 0.0.0.0) but is opt-in and warned about, because then
+// the token is the ONLY thing between the network and a shell.
+
+import crypto from 'node:crypto';
+
+// 32 bytes of entropy, base64url. Long enough that guessing is hopeless, short
+// enough to paste from a terminal.
+export function newToken() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * Constant-time string compare. `crypto.timingSafeEqual` throws on a length
+ * mismatch, which would itself leak the length — so both sides are hashed first,
+ * making every comparison the same length.
+ */
+export function safeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const ha = crypto.createHash('sha256').update(a).digest();
+  const hb = crypto.createHash('sha256').update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+/** Loopback check — decides whether binding needs a warning. */
+export function isLoopback(addr) {
+  const a = String(addr || '').trim().toLowerCase();
+  if (a === 'localhost' || a === '::1' || a === '[::1]') return true;
+  if (/^127(\.\d{1,3}){3}$/.test(a)) return true;
+  return false;
+}
+
+/**
+ * Is this request allowed to CHANGE something? A browser sends `Origin` on every
+ * state-changing cross-origin request (and on same-origin POSTs too), so a
+ * mismatch means the request came from a page we do not control. Requests with no
+ * Origin at all are allowed only when they carry the bearer token — that is a
+ * script (curl), not a browser being abused by another site.
+ */
+export function sameOriginOk(req, expectedHosts) {
+  const origin = req.headers.origin || req.headers.referer;
+  if (!origin) return null;                 // caller decides (token-only scripts)
+  let host;
+  try { host = new URL(origin).host; } catch { return false; }
+  return expectedHosts.includes(host);
+}
+
+/** Parse `Cookie: a=1; b=2`. Returns {} for anything malformed. */
+export function parseCookies(header) {
+  const out = {};
+  const s = String(header || '');
+  if (!s) return out;
+  for (const part of s.split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    const k = part.slice(0, i).trim();
+    if (!k) continue;
+    out[k] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * The request's credential, from either place:
+ *   * `Authorization: Bearer <token>` — scripts, curl, the CLI;
+ *   * the `hncode_web` cookie        — the browser, set by POST /api/login.
+ */
+export function requestSecret(req, cookieName = 'hncode_web') {
+  const auth = String(req.headers.authorization || '');
+  if (auth.toLowerCase().startsWith('bearer ')) return auth.slice(7).trim();
+  const cookies = parseCookies(req.headers.cookie);
+  return cookies[cookieName] || '';
+}
+
+export function isAuthed(req, token, cookieName) {
+  return safeEqual(requestSecret(req, cookieName), token);
+}

package/src/web-daemon-cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Entry point for the global web UI daemon.
+//
+// Normally spawned by web-daemon-client.js from a TUI session; it can also be
+// run by hand (`node src/web-daemon-cli.js`) to keep the UI up without a TUI.
+//
+// Everything it would have printed to a terminal goes to the log file instead,
+// because a daemon started detached has no terminal to report to — that log is
+// the only place a bind failure can be read afterwards.
+
+import { startWebDaemon, defaultDaemonPipe } from './web-daemon.js';
+import { resolveConfig } from './config.js';
+
+const cfg = resolveConfig();
+
+async function main() {
+  const host = process.env.HNCODE_WEB_HOST || cfg.webHost || '127.0.0.1';
+  const port = Number(process.env.HNCODE_WEB_PORT ?? (cfg.webPort == null ? 8765 : cfg.webPort));
+  const pipePath = defaultDaemonPipe();
+
+  let daemon;
+  try {
+    daemon = await startWebDaemon({ host, port, pipePath });
+  } catch (e) {
+    // The port is the usual failure: something else already holds it. Say WHICH
+    // address and how to change it, because a detached daemon cannot ask.
+    if (e && (e.code === 'EADDRINUSE' || /EADDRINUSE/.test(String(e.message)))) {
+      process.stderr.write(
+        `[web-daemon] port ${port} on ${host} is already in use.\n`
+        + '[web-daemon] Choose another in config.toml:  web_port = 8766\n'
+        + '[web-daemon] or for this run:  HNCODE_WEB_PORT=8766\n',
+      );
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  if (daemon.pipeError) {
+    // Another daemon already owns the pipe. Not an error for the caller — this
+    // one simply has nothing to add, so it exits and the TUI keeps using the
+    // existing daemon.
+    process.stderr.write(`[web-daemon] another daemon already owns ${pipePath}; exiting\n`);
+    daemon.close();
+    process.exit(0);
+  }
+
+  process.stdout.write(
+    `[web-daemon] listening on ${daemon.url} (pid ${process.pid})\n`
+    + `[web-daemon] pipe: ${daemon.pipePath}\n`,
+  );
+
+  const shutdown = () => {
+    try { daemon.close(); } catch { /* already closed */ }
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((e) => {
+  process.stderr.write(`[web-daemon] fatal: ${(e && e.stack) || e}\n`);
+  process.exit(1);
+});

package/src/web-daemon-client.js

@@ -0,0 +1,203 @@
+// TUI side of the global web UI.
+//
+// The user's model is: "/web" opens ONE web UI for this machine. If a daemon is
+// already running, this session simply registers with it and does NOT start a
+// second server — the existing one already holds the fixed port and token, and a
+// second one could not bind that port anyway.
+//
+// So the flow is: probe -> (spawn if absent) -> register -> heartbeat. The
+// session's own per-session server (web.js) still exists, because that is where
+// the transcript and the actions live; the daemon only routes to it.
+
+import net from 'node:net';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import cp from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveConfig } from './config.js';
+import { HEARTBEAT_MS, defaultDaemonPipe } from './web-daemon.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** Send one line-JSON request over the daemon pipe. Never throws. */
+export function daemonCall(req, opts = {}) {
+  const pipePath = opts.pipePath || defaultDaemonPipe();
+  const timeoutMs = opts.timeoutMs || 2000;
+  return new Promise((resolve) => {
+    let done = false, sock = null;
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { if (sock) sock.destroy(); } catch { /* already gone */ }
+      resolve(r);
+    };
+    const timer = setTimeout(() => finish({ ok: false, error: 'timeout' }), timeoutMs);
+    try { sock = net.connect(pipePath); }
+    catch (e) { finish({ ok: false, error: e.message }); return; }
+    let buf = '';
+    sock.on('connect', () => {
+      try { sock.write(JSON.stringify(req) + '\n'); }
+      catch (e) { finish({ ok: false, error: e.message }); }
+    });
+    sock.on('data', (d) => {
+      buf += d.toString('utf8');
+      const i = buf.indexOf('\n');
+      if (i < 0) return;
+      let parsed = null;
+      try { parsed = JSON.parse(buf.slice(0, i)); } catch { /* malformed */ }
+      finish(parsed || { ok: false, error: 'bad reply' });
+    });
+    sock.on('error', (e) => finish({ ok: false, error: e.message }));
+  });
+}
+
+/** Is a daemon already listening on the pipe? */
+export async function daemonAlive(opts = {}) {
+  const r = await daemonCall({ op: 'ping' }, opts);
+  return r && r.ok === true;
+}
+
+/**
+ * The daemon's own address, as it reports it. Use this instead of assuming the
+ * configured port: when the config says `web_port = 0` the OS picks one, and a
+ * guessed URL would point nowhere.
+ */
+export async function daemonInfo(opts = {}) {
+  const r = await daemonCall({ op: 'ping' }, opts);
+  if (!r || !r.ok) return null;
+  const host = r.host || '127.0.0.1';
+  return { host, port: r.port, sessions: r.sessions, url: `http://${host}:${r.port}/` };
+}
+
+/**
+ * Ask the daemon to shut down and release its port.
+ *
+ * Needed because the daemon is started DETACHED on purpose — `child.kill()` from
+ * the spawning process does not reach it once that process has moved on (which is
+ * what left orphaned daemons behind in testing). This is the supported way to
+ * stop one from outside.
+ */
+export async function stopDaemon(opts = {}) {
+  const r = await daemonCall({ op: 'shutdown' }, opts);
+  return !!(r && r.ok);
+}
+
+/**
+ * Start the daemon as a DETACHED process.
+ *
+ * Detached and `unref`ed on purpose: the daemon must outlive the terminal that
+ * happened to start it. Its own idle rule (exit once the last session
+ * deregisters) is what stops it from lingering forever.
+ *
+ * Returns once it answers on the pipe, or throws with what went wrong — a silent
+ * failure here would leave /web reporting success with nothing serving it.
+ */
+export async function spawnDaemon(opts = {}) {
+  const cfg = resolveConfig();
+  const pipePath = opts.pipePath || defaultDaemonPipe();
+  // An explicit host (from `/web <ip>`) wins over the config value, so the same
+  // command that asks for a network-reachable session server also binds the
+  // daemon to the network. Without this the daemon kept 127.0.0.1 and the
+  // browser's connection to the listed URL died with "no data sent".
+  const daemonHost = opts.host || cfg.webHost || '127.0.0.1';
+  const logFile = path.join(os.homedir(), '.hncode', 'web-daemon.log');
+  try { fs.mkdirSync(path.dirname(logFile), { recursive: true }); } catch { /* exists */ }
+  let out = 'ignore';
+  try { out = fs.openSync(logFile, 'a'); } catch { out = 'ignore'; }
+
+  const entry = path.join(HERE, 'web-daemon-cli.js');
+  if (!fs.existsSync(entry)) throw new Error(`daemon entry not found: ${entry}`);
+
+  const child = cp.spawn(process.execPath, [entry], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      HNCODE_WEB_PIPE: pipePath,
+      HNCODE_WEB_HOST: daemonHost,
+      HNCODE_WEB_PORT: String(cfg.webPort == null ? 8765 : cfg.webPort),
+    },
+  });
+  child.unref();
+
+  // Wait for it to answer. A bind failure (port taken by something else) shows up
+  // here as a timeout, which is the honest report: the daemon is not serving.
+  const deadline = Date.now() + (opts.waitMs || 8000);
+  let lastErr = 'did not start';
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 120));
+    const ping = await daemonCall({ op: 'ping' }, { pipePath, timeoutMs: 800 });
+    if (ping && ping.ok) return { spawned: true, child, pipePath, logFile };
+    if (ping && ping.error && ping.error !== 'timeout') lastErr = ping.error;
+  }
+  throw new Error(`web daemon did not start (${lastErr}); see ${logFile}`);
+}
+
+/**
+ * Attach this session to the global daemon.
+ *
+ * @param {object} info  { id, port, token, title, workspace }
+ *   `port`/`token` describe THIS session's own web.js server, which the daemon
+ *   proxies to. Without them the daemon can only serve the session read-only.
+ * @returns {Promise<{ ok, spawned, reused, pipePath, heartbeat }>}
+ */
+export async function attachToDaemon(info, opts = {}) {
+  const pipePath = opts.pipePath || defaultDaemonPipe();
+  let spawned = false;
+
+  if (!(await daemonAlive({ pipePath }))) {
+    await spawnDaemon({ pipePath, waitMs: opts.waitMs, host: info.host });
+    spawned = true;
+  }
+
+  const reg = await daemonCall({
+    op: 'register',
+    id: info.id,
+    port: info.port,
+    token: info.token,
+    title: info.title || '',
+    workspace: info.workspace || '',
+    pid: process.pid,
+  }, { pipePath, timeoutMs: 4000 });
+
+  if (!reg || !reg.ok) {
+    throw new Error(`could not register with the web daemon: ${(reg && reg.error) || 'no reply'}`);
+  }
+
+  // Heartbeat so a killed process is not shown as live forever. `unref` keeps the
+  // timer from holding the event loop open on its own.
+  const hb = setInterval(() => {
+    daemonCall({ op: 'touch', id: info.id }, { pipePath, timeoutMs: 1500 }).catch(() => {});
+  }, Math.max(5000, HEARTBEAT_MS));
+  if (hb.unref) hb.unref();
+
+  const detach = () => {
+    clearInterval(hb);
+    daemonCall({ op: 'unregister', id: info.id }, { pipePath, timeoutMs: 1500 }).catch(() => {});
+  };
+
+  // Ask the daemon where it actually is, rather than trusting the configured
+  // port: `web_port = 0` means the OS chose one.
+  const addr = await daemonInfo({ pipePath, timeoutMs: 2000 });
+  const host = (addr && addr.host) || '127.0.0.1';
+  const port = (addr && addr.port) != null ? addr.port : null;
+  const url = port == null ? null : `http://${host}:${port}/s/${encodeURIComponent(info.id)}/`;
+
+  return {
+    ok: true,
+    spawned,
+    reused: !spawned,
+    pipePath,
+    host,
+    port,
+    // The per-SESSION URL the user should open. The daemon's root lists every
+    // session, so both are reported and the TUI can print whichever it wants.
+    url,
+    rootUrl: port == null ? null : `http://${host}:${port}/`,
+    heartbeat: hb,
+    detach,
+  };
+}