claude-code-hub 0.22.0 → 0.24.0

package/lib/net-guard.js

@@ -0,0 +1,267 @@
+'use strict';
+
+// Network boundary for a local-only dev server.
+//
+// Binding loopback is necessary but not sufficient. Three distinct attackers:
+//
+//   * LAN peer — http://192.168.1.42:3541/api/... The loopback bind stops this
+//     outright; the handshake never completes off-box.
+//   * DNS rebinding — the victim loads evil.com, the attacker re-resolves that
+//     name to 127.0.0.1, and the page fetches http://evil.com:3541/api/...
+//     The page's origin *is* evil.com:3541, so the request is same-origin and
+//     CORS never fires; the connection is to loopback, so the bind is satisfied.
+//     The only thing that differs from a legitimate request is the Host header,
+//     which script cannot forge. A Host allowlist is the entire defense.
+//   * Plain CSRF — evil.com POSTs straight at 127.0.0.1:3541. Host is a real
+//     allowlisted value, so hostGuard passes it; this needs a separate Origin /
+//     Sec-Fetch-Site check on state-changing methods.
+//
+// There is no authentication. Exposing this to a network means trusting everyone
+// on it with the user's Claude Code history.
+//
+// CANONICAL COPY: scripts/security-lib/net-guard.js in the claude-code-hub repo.
+// Run scripts/sync-security-lib.sh after editing.
+
+const LOOPBACK_HOSTS = new Set([
+  'localhost',
+  '127.0.0.1',
+  '::1',
+  '0:0:0:0:0:0:0:1',
+  '::ffff:127.0.0.1',
+]);
+
+// Hoisted: parseHostHeader runs on every request, and neither the regex nor the
+// predicate depends on the argument.
+const PORT_RE = /^[0-9]{1,5}$/;
+// The port is validated but not compared — the listen(0) fallbacks make the real
+// port dynamic, so only the host is allowlisted.
+const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
+
+function isLoopbackAddress(host) {
+  if (!host) return false;
+  const h = String(host).toLowerCase();
+  return LOOPBACK_HOSTS.has(h) || h.startsWith('127.');
+}
+
+// Hand-parsed rather than via new URL(), which is far more permissive than we
+// want here and happily accepts things no real client sends. Returns the bare
+// hostname, lowercased, or null if the header is malformed.
+//
+// The port is deliberately ignored: ports are dynamic in these apps because of
+// the listen(0) fallback when the default is busy, so pinning one would break
+// the fallback path.
+function parseHostHeader(value) {
+  if (typeof value !== 'string') return null;
+  const raw = value.trim();
+  if (!raw || raw.length > 259) return null;
+
+  // Reject whitespace and control characters. Written as a code-point scan rather
+  // than a character class so it cannot be misread — a stray range in a regex
+  // here would silently reject legitimate hostnames containing a dash.
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) return null;
+  }
+  if (raw.includes('@')) return null; // userinfo has no business in a Host header
+
+  let host;
+  if (raw.startsWith('[')) {
+    const end = raw.indexOf(']');
+    if (end === -1) return null;
+    host = raw.slice(1, end);
+    const rest = raw.slice(end + 1);
+    if (rest && !(rest.startsWith(':') && validPort(rest.slice(1)))) return null;
+  } else {
+    const parts = raw.split(':');
+    if (parts.length > 2) return null; // bare IPv6 without brackets, or garbage
+    host = parts[0];
+    if (parts.length === 2 && !validPort(parts[1])) return null;
+  }
+
+  if (!host) return null;
+  if (host.endsWith('.')) host = host.slice(0, -1); // one trailing root dot is legal
+  if (!host) return null;
+  return host.toLowerCase();
+}
+
+function parseList(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function getFlag(name) {
+  const idx = process.argv.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = process.argv[idx];
+  if (arg.includes('=')) return arg.slice(arg.indexOf('=') + 1);
+  const next = process.argv[idx + 1];
+  return next && !next.startsWith('--') ? next : null;
+}
+
+/**
+ * @param {{appName?: string}} [config]
+ */
+function createNetGuard(config = {}) {
+  const appName = config.appName || 'This app';
+
+  const BIND_HOST = getFlag('host') || process.env.HOST || '127.0.0.1';
+  const BIND_HOST_LC = BIND_HOST.toLowerCase();
+  const EXPOSED = !isLoopbackAddress(BIND_HOST);
+  // Resolved here and re-exported so the hub can forward the same value to its
+  // children rather than re-parsing the flag with its own argv scanner — a parent
+  // and child that disagree means the shell serves while every iframe 403s.
+  const ALLOWED_HOSTS = getFlag('allowed-hosts') || process.env.ALLOWED_HOSTS || '';
+  const extraHosts = new Set(parseList(ALLOWED_HOSTS));
+
+  // The hub frames each sub-app, so its origin must be accepted as an Origin and
+  // permitted as a framing ancestor.
+  let hubOrigin = null;
+  if (process.env.HUB_URL) {
+    try { hubOrigin = new URL(process.env.HUB_URL).origin; } catch { /* ignore a malformed HUB_URL */ }
+  }
+
+  // Resolved only once listen() succeeds — the requested port may have been busy.
+  let actualPort = null;
+
+  function hostAllowed(host) {
+    if (!host) return false;
+    if (isLoopbackAddress(host)) return true;
+    if (extraHosts.has(host)) return true;
+    // Binding a specific non-loopback address implies that address is a valid name for us.
+    if (EXPOSED && host === BIND_HOST_LC) return true;
+    return false;
+  }
+
+  function hostGuard(req, res, next) {
+    const host = parseHostHeader(req.headers.host);
+    if (hostAllowed(host)) return next();
+    res.status(403).type('text/plain').send(
+      `403 Forbidden - unrecognized Host header: ${req.headers.host || '(none)'}\n\n` +
+      `${appName} only answers requests addressed to localhost. This protects you\n` +
+      `from DNS rebinding, where a website you visit re-points its own hostname at\n` +
+      `127.0.0.1 in order to read your local data.\n\n` +
+      `If you meant to reach this from another machine, restart with:\n` +
+      `  --host 0.0.0.0 --allowed-hosts=${host || '<your-hostname>'}\n\n` +
+      `Only do that on a network you trust - there is no authentication.\n`
+    );
+  }
+
+  // true = allow, false = block, null = no Origin header, caller decides.
+  function originVerdict(origin) {
+    if (!origin || origin === 'null') return null;
+    let parsed;
+    try { parsed = new URL(origin); } catch { return false; }
+    if (hubOrigin && parsed.origin === hubOrigin) return true;
+    if (!isLoopbackAddress(parsed.hostname)) return false;
+    // Same port, any loopback spelling. A different local port is a different app
+    // and has no business driving this one.
+    if (actualPort && parsed.port && Number(parsed.port) !== Number(actualPort)) return false;
+    return true;
+  }
+
+  function originGuard(req, res, next) {
+    if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next();
+
+    const verdict = originVerdict(req.headers.origin);
+    if (verdict === true) return next();
+    if (verdict === false) {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-origin ${req.method} from ${req.headers.origin} is not allowed.\n`);
+    }
+
+    // No Origin header: a non-browser client (curl, the CLI, the hub's own fetch).
+    // Trust it unless the browser explicitly tells us otherwise.
+    const site = req.headers['sec-fetch-site'];
+    if (site && site !== 'same-origin' && site !== 'none') {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-site ${req.method} (Sec-Fetch-Site: ${site}) is not allowed.\n`);
+    }
+    return next();
+  }
+
+  // Constant for the life of the process, and frameGuard runs ahead of
+  // express.static — so this is built once rather than per asset fetch.
+  //
+  // Under the hub, X-Frame-Options is deliberately omitted: it has no multi-origin
+  // form, and sending SAMEORIGIN would break the hub's iframes.
+  //
+  // The port is wildcarded rather than pinned to HUB_URL's. The hub spawns its
+  // children before it binds, so if its own preferred port is busy it hands them a
+  // HUB_URL with the wrong port and every iframe would break. Any loopback port may
+  // frame us; that is not the threat being addressed here — a remote page still
+  // cannot, which is what matters.
+  //
+  // No IPv6 literal: Chrome rejects `http://[::1]:*` as a source expression and
+  // logs it on every framed load. The hub's own origin is added verbatim instead,
+  // which covers a hub reached over [::1].
+  let CSP;
+  if (hubOrigin) {
+    const ancestors = ["'self'", 'http://localhost:*', 'http://127.0.0.1:*'];
+    if (!/^http:\/\/(localhost|127\.0\.0\.1)(:|$)/.test(hubOrigin)) ancestors.push(hubOrigin);
+    CSP = `frame-ancestors ${ancestors.join(' ')}`;
+  } else {
+    CSP = "frame-ancestors 'none'";
+  }
+
+  function frameGuard(_req, res, next) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('Content-Security-Policy', CSP);
+    if (!hubOrigin) res.setHeader('X-Frame-Options', 'DENY');
+    next();
+  }
+
+  /**
+   * Bind BIND_HOST, then opportunistically serve the other loopback family on the
+   * same resolved port via a second server sharing the same request handler.
+   *
+   * That second bind is what keeps `http://localhost:<port>` working no matter how
+   * the OS resolver orders A/AAAA records - binding only 127.0.0.1 breaks hosts
+   * where `localhost` resolves to ::1, and vice versa. Doing it on the *resolved*
+   * port means every existing URL, startup banner and postMessage origin is
+   * unchanged. Failures are swallowed: it is an optimization, not a requirement.
+   *
+   * Returns the primary server, so callers keep attaching their own 'error'
+   * handler for the EADDRINUSE fallback.
+   *
+   * @param {any} app express app (or any http request handler)
+   * @param {number} port 0 selects a free port
+   * @param {(port: number) => void} [onReady]
+   * @param {{maxHeaderSize?: number}} [opts]
+   */
+  function listenLoopback(app, port, onReady, opts = {}) {
+    const http = require('http');
+    const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
+    const makeServer = (handler) => http.createServer(serverOpts, handler);
+    const server = makeServer(app);
+    let secondary = null;
+
+    server.on('listening', () => {
+      actualPort = server.address().port;
+      if (!EXPOSED) {
+        const otherFamily = BIND_HOST.includes(':') ? '127.0.0.1' : '::1';
+        try {
+          secondary = makeServer(app);
+          secondary.on('error', () => {}); // that family may not exist on this host
+          secondary.listen({ host: otherFamily, port: actualPort, ipv6Only: otherFamily === '::1' });
+        } catch { /* best effort */ }
+      }
+      if (onReady) onReady(actualPort);
+    });
+    server.on('close', () => { try { if (secondary) secondary.close(); } catch { /* already gone */ } });
+
+    server.listen(port, BIND_HOST);
+    return server;
+  }
+
+  function exposureWarning() {
+    if (!EXPOSED) return null;
+    return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
+  }
+
+  return { BIND_HOST, ALLOWED_HOSTS, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+}
+
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "claude-code-hub",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
-    "claude-code-hub": "./server.js"
+    "claude-code-hub": "server.js"
   },
   "scripts": {
     "start": "node server.js",
     "dev": "node server.js --open",
-    "lint": "npx @biomejs/biome check public/app.js server.js",
+    "lint": "npx @biomejs/biome check public/app.js server.js && npm run check:escaping && npm run check:security-lib",
     "lint:fix": "npx @biomejs/biome check --fix public/app.js server.js",
-    "prepare": "husky"
+    "prepare": "husky",
+    "check:escaping": "node scripts/check-escaping.mjs",
+    "check:security-lib": "bash scripts/sync-security-lib.sh --check"
   },
   "repository": {
     "type": "git",
@@ -35,10 +37,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "^0.12.1",
-    "claude-code-kanban": "^4.17.0",
-    "claude-code-marketplace": "^0.12.1",
-    "claude-code-memory-explorer": "^0.9.1",
+    "claude-code-cost": "^0.14.0",
+    "claude-code-kanban": "^4.19.0",
+    "claude-code-marketplace": "^0.13.0",
+    "claude-code-memory-explorer": "^0.10.0",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },
@@ -47,7 +49,8 @@
   },
   "files": [
     "server.js",
-    "public/**/*"
+    "public/**/*",
+    "lib/**/*"
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",

package/public/app.js

@@ -68,6 +68,10 @@ function originOf(appId) {
 }
 
 function postTo(appId, message) {
+  // Before the iframe commits its src its contentWindow is still on the hub's own
+  // origin, so a send addressed to the sub-app origin is refused and logged. The
+  // load handler posts the current state anyway, so skipping here loses nothing.
+  if (!loadedApps.has(appId)) return;
   iframes[appId]?.contentWindow?.postMessage(message, originOf(appId));
 }
 

package/server.js

@@ -3,8 +3,8 @@
 const { spawn } = require('child_process');
 const express = require('express');
 const fs = require('fs');
-const http = require('http');
 const path = require('path');
+const { createNetGuard } = require('./lib/net-guard');
 
 function getArg(name) {
   const idx = process.argv.findIndex((a) => a.startsWith(`--${name}`));
@@ -23,6 +23,11 @@ const MEMORY_PORT = parseInt(getArg('memory-port') || '3544', 10);
 const children = [];
 const actualPorts = { marketplace: MARKETPLACE_PORT, kanban: KANBAN_PORT, cost: COST_PORT, memory: MEMORY_PORT };
 
+// Created before spawnApp so the same host/allowed-hosts decision reaches the
+// children. Without that propagation, `--host 0.0.0.0` would expose the hub shell
+// while every iframe 403'd on its own Host check.
+const net = createNetGuard({ appName: 'Claude Code Hub' });
+
 function spawnApp(name, cmd, args, envPort) {
   const child = spawn(cmd, args, {
     cwd: __dirname,
@@ -31,6 +36,8 @@ function spawnApp(name, cmd, args, envPort) {
       PORT: String(envPort),
       CLAUDE_HUB: '1',
       HUB_URL: `http://localhost:${HUB_PORT}`,
+      HOST: net.BIND_HOST,
+      ALLOWED_HOSTS: net.ALLOWED_HOSTS,
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });
@@ -105,7 +112,8 @@ const memoryPath = resolveApp('memory', 'claude-code-memory-explorer');
 
 // Raise header size limit to 64KB — localhost cookies from sibling apps can pile up and
 // trip Node's default 16KB limit, breaking iframes with HTTP 431.
-const NODE_HDR = '--max-http-header-size=65536';
+const HDR_BYTES = 65536;
+const NODE_HDR = `--max-http-header-size=${HDR_BYTES}`;
 
 spawnApp('marketplace', process.execPath, [NODE_HDR, marketplacePath, `--port=${MARKETPLACE_PORT}`], MARKETPLACE_PORT);
 spawnApp('kanban', process.execPath, [NODE_HDR, kanbanPath], KANBAN_PORT);
@@ -114,6 +122,12 @@ spawnApp('memory', process.execPath, [NODE_HDR, memoryPath, `--port=${MEMORY_POR
 
 const app = express();
 
+// Mounted before the routes below, which are registered ahead of the first
+// app.use() and would otherwise bypass the guards entirely.
+app.use(net.hostGuard);
+app.use(net.frameGuard);
+app.use(net.originGuard);
+
 // The accent hex per color theme, read from the same registry generate-themes.mjs compiles into each
 // sub-app's themes.css. Served rather than hand-copied into public/app.js so there is one source of
 // truth; the palette is the hub's only themed surface, so only ember (the accent role) is needed.
@@ -187,31 +201,26 @@ app.get('/api/resolve-path', (req, res) => {
 
 app.use(express.static(path.join(__dirname, 'public')));
 
-const server = http.createServer({ maxHeaderSize: 65536 }, app);
-server.listen(HUB_PORT, () => {
-  const actual = server.address().port;
+const onReady = (actual) => {
   printBanner(actual);
   if (process.argv.includes('--open')) {
     import('open').then((m) => m.default(`http://localhost:${actual}`));
   }
-});
+};
+
+const server = net.listenLoopback(app, HUB_PORT, onReady, { maxHeaderSize: HDR_BYTES });
 
 function printBanner(port) {
   console.log(`Claude Code Hub running at http://localhost:${port}`);
+  const warning = net.exposureWarning();
+  if (warning) console.log(warning);
   console.log('Type "q" or "exit" to stop the server');
 }
 
 server.on('error', (err) => {
   if (err.code === 'EADDRINUSE' || err.code === 'EACCES') {
     console.log(`Port ${HUB_PORT} in use, trying random port...`);
-    const fallback = http.createServer({ maxHeaderSize: 65536 }, app);
-    fallback.listen(0, () => {
-      const actual = fallback.address().port;
-      printBanner(actual);
-      if (process.argv.includes('--open')) {
-        import('open').then((m) => m.default(`http://localhost:${actual}`));
-      }
-    });
+    net.listenLoopback(app, 0, onReady, { maxHeaderSize: HDR_BYTES });
   } else {
     throw err;
   }