claude-code-kanban 4.17.0 → 4.19.0

package/lib/contain.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Path containment check.
+//
+// The obvious implementation — `child.startsWith(root)` — is wrong twice over:
+// it accepts a sibling directory that merely shares a prefix ("/plugins/foo-evil"
+// passes a check for "/plugins/foo"), and it is blind to symlinks, `..`, casing
+// and Windows 8.3 short names. This uses path.relative instead, and canonicalises
+// both sides first.
+//
+// CANONICAL COPY: scripts/security-lib/contain.js in the claude-code-hub repo.
+// Run scripts/sync-security-lib.sh after editing.
+
+const path = require('path');
+const fs = require('fs');
+
+const IS_WIN = process.platform === 'win32';
+
+// realpath the deepest existing ancestor, then re-append the non-existent tail,
+// so a not-yet-created file under a symlinked directory still canonicalises.
+function realpathDeepest(target) {
+  let cur = target;
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return target; // reached the volume root, nothing resolvable
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function canonical(target, deepest) {
+  let out = path.resolve(target);
+  if (deepest) out = realpathDeepest(out);
+  else { try { out = fs.realpathSync.native(out); } catch { /* may not exist yet */ } }
+  // realpathSync.native has already expanded 8.3 short names (PROGRA~1) and fixed
+  // the casing of the existing portion; lowercase covers the rest.
+  return IS_WIN ? out.toLowerCase() : out;
+}
+
+function beneath(canonicalChild, root) {
+  const rel = path.relative(canonical(root, false), canonicalChild);
+  // '' means child === root. An absolute rel means a different drive or UNC share,
+  // which path.relative signals by giving up — reject those.
+  if (rel === '') return true;
+  if (path.isAbsolute(rel)) return false;
+  return rel !== '..' && !rel.startsWith(`..${path.sep}`);
+}
+
+/**
+ * True iff `child` is `root` itself or lies beneath it.
+ * @param {string} child
+ * @param {string} root
+ */
+function isContained(child, root) {
+  if (typeof child !== 'string' || typeof root !== 'string' || !child || !root) return false;
+  return beneath(canonical(child, true), root);
+}
+
+/**
+ * True iff `child` is contained by any of `roots`. Canonicalises the child once
+ * instead of once per root — callers testing a single path against several roots
+ * were paying that walk repeatedly.
+ * @param {string} child
+ * @param {string[]} roots
+ */
+function isContainedAny(child, roots) {
+  if (typeof child !== 'string' || !child || !Array.isArray(roots)) return false;
+  const c = canonical(child, true);
+  return roots.some((r) => typeof r === 'string' && r && beneath(c, r));
+}
+
+module.exports = { isContained, isContainedAny, realpathDeepest };

package/lib/inline-assets.js

@@ -0,0 +1,238 @@
+// Inlines an HTML file's local assets so it renders standalone inside the preview's
+// `srcdoc` iframe. An `about:srcdoc` document has no URL of its own, so every relative
+// href resolves against the app origin and 404s — the only way a sibling stylesheet,
+// script or image can reach the frame is embedded in the document text.
+//
+// Remote refs (https:, //cdn, data:) are left untouched: they already resolve.
+
+const path = require('path');
+const fs = require('fs').promises;
+
+// Individually large assets are the ones that blow up as base64 (+33%), and the total
+// guards the modal: the whole document is handed to the client in one JSON response.
+// Both count bytes on disk, charged once per unique file — the delivered document is
+// larger than the total whenever an asset is base64'd or referenced twice.
+const MAX_ASSET_BYTES = 4 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+// @import chains are followed, so a cycle needs both a depth stop and a seen-set.
+const MAX_IMPORT_DEPTH = 5;
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.bmp': 'image/bmp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.ogv': 'video/ogg',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.json': 'application/json',
+  '.css': 'text/css',
+  '.js': 'text/javascript'
+};
+
+function isRemoteRef(ref) {
+  return !ref || /^[a-z][a-z0-9+.-]*:/i.test(ref) || ref.startsWith('//') || ref.startsWith('#');
+}
+
+function mimeFor(file) {
+  return MIME_BY_EXT[path.extname(file).toLowerCase()] || 'application/octet-stream';
+}
+
+// Reads an attribute out of a tag, quoted or bare. Returns undefined when absent.
+function attrOf(tag, name) {
+  const q = new RegExp(`${name.replace(':', '\\:')}\\s*=\\s*(['"])(.*?)\\1`, 'i');
+  return tag.match(q)?.[2] ?? tag.match(new RegExp(`${name.replace(':', '\\:')}\\s*=\\s*([^\\s>]+)`, 'i'))?.[1];
+}
+
+// Rewrites every match of `re` in one pass: `fn` receives the match array and returns
+// the replacement, or null to leave that match alone. Replacements are resolved
+// concurrently (each reads its own asset) and spliced by offset, so the string is
+// rebuilt once instead of once per match.
+async function replaceMatches(text, re, fn) {
+  const matches = [...text.matchAll(re)];
+  if (!matches.length) return text;
+  const replacements = await Promise.all(matches.map(m => fn(m)));
+  const out = [];
+  let cursor = 0;
+  matches.forEach((m, i) => {
+    if (replacements[i] == null) return;
+    out.push(text.slice(cursor, m.index), replacements[i]);
+    cursor = m.index + m[0].length;
+  });
+  out.push(text.slice(cursor));
+  return out.join('');
+}
+
+// One context threads through a whole document: the cache means an asset referenced by
+// twenty rules is read, size-checked and charged exactly once, and nested @import/url()
+// chains can't each spend the full allowance.
+async function loadAsset(absPath, ctx) {
+  if (!ctx.cache.has(absPath)) {
+    ctx.cache.set(
+      absPath,
+      (async () => {
+        const stat = await fs.stat(absPath);
+        if (!stat.isFile()) throw new Error('not a file');
+        if (stat.size > MAX_ASSET_BYTES || ctx.spent + stat.size > MAX_TOTAL_BYTES) {
+          ctx.skipped.push({ path: absPath, size: stat.size, reason: 'too large' });
+          return null;
+        }
+        ctx.spent += stat.size;
+        return fs.readFile(absPath);
+      })()
+    );
+  }
+  return ctx.cache.get(absPath);
+}
+
+async function loadText(absPath, ctx) {
+  return (await loadAsset(absPath, ctx))?.toString('utf8') ?? null;
+}
+
+async function toDataUri(absPath, ctx) {
+  const buf = await loadAsset(absPath, ctx);
+  return buf === null ? null : `data:${mimeFor(absPath)};base64,${buf.toString('base64')}`;
+}
+
+// Resolves a ref against `baseDir` and hands the loaded asset to `use`. Remote refs and
+// unreadable files yield null, which every caller treats as "leave the markup as
+// authored" so the frame degrades to the pre-inlining behaviour.
+async function withAsset(ref, baseDir, use) {
+  if (isRemoteRef(ref)) return null;
+  try {
+    return await use(path.resolve(baseDir, ref));
+  } catch {
+    return null;
+  }
+}
+
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?(['"]?)([^'")\s;]+)\1\s*\)?\s*([^;]*);/gi;
+const CSS_URL = /url\(\s*(['"]?)([^'")]+)\1\s*\)/gi;
+
+// Rewrites url(...) targets and follows @import into the imported sheet's own directory —
+// a nested sheet's relative refs are relative to *it*, not to the document.
+async function inlineCss(css, baseDir, ctx, depth = 0, seen = new Set()) {
+  let out = css;
+
+  if (depth < MAX_IMPORT_DEPTH) {
+    out = await replaceMatches(out, CSS_IMPORT, ([, , ref, media]) =>
+      withAsset(ref, baseDir, async abs => {
+        if (seen.has(abs)) return null;
+        const text = await loadText(abs, ctx);
+        if (text === null) return null;
+        const nested = await inlineCss(text, path.dirname(abs), ctx, depth + 1, new Set([...seen, abs]));
+        // A media query on the @import has to survive as a wrapper or the rules leak.
+        return media.trim() ? `@media ${media.trim()}{\n${nested}\n}` : nested;
+      })
+    );
+  }
+
+  return replaceMatches(out, CSS_URL, ([, , ref]) =>
+    withAsset(ref, baseDir, async abs => {
+      const uri = await toDataUri(abs, ctx);
+      return uri && `url("${uri}")`;
+    })
+  );
+}
+
+// `</script>` anywhere in inlined JS (a string, a regex, a template) would close the tag
+// early and dump the rest as markup.
+function escapeScript(js) {
+  return js.replace(/<\/script/gi, '<\\/script');
+}
+
+function inlineStylesheets(html, baseDir, ctx) {
+  return replaceMatches(html, /<link\b[^>]*>/gi, async ([tag]) => {
+    if (!/rel\s*=\s*(['"]?)[^'">]*\bstylesheet\b/i.test(tag)) return null;
+    return withAsset(attrOf(tag, 'href'), baseDir, async abs => {
+      const css = await loadText(abs, ctx);
+      if (css === null) return null;
+      const inlined = await inlineCss(css, path.dirname(abs), ctx, 0, new Set([abs]));
+      const media = attrOf(tag, 'media');
+      return `<style${media ? ` media="${media}"` : ''}>\n${inlined}\n</style>`;
+    });
+  });
+}
+
+function inlineStyleElements(html, baseDir, ctx) {
+  return replaceMatches(html, /<style\b[^>]*>([\s\S]*?)<\/style>/gi, async ([tag, css]) => {
+    if (!/url\(|@import/i.test(css)) return null;
+    const inlined = await inlineCss(css, baseDir, ctx);
+    return inlined === css ? null : tag.replace(css, inlined);
+  });
+}
+
+function inlineScripts(html, baseDir, ctx) {
+  return replaceMatches(html, /<script\b[^>]*\bsrc\s*=[^>]*>\s*<\/script>/gi, ([tag]) =>
+    withAsset(attrOf(tag, 'src'), baseDir, async abs => {
+      const js = await loadText(abs, ctx);
+      if (js === null) return null;
+      // Keep type= (module vs classic changes semantics); drop src/defer/async, which
+      // mean nothing once the body is inline.
+      const type = attrOf(tag, 'type');
+      return `<script${type ? ` type="${type}"` : ''}>\n${escapeScript(js)}\n</script>`;
+    })
+  );
+}
+
+// src/poster/href on media and image tags. `<use href>` covers sprite sheets, which are
+// the one SVG case that silently renders nothing when unresolved.
+const SRC_ATTR_TAGS = /<(img|source|video|audio|use)\b[^>]*>/gi;
+const SRC_ATTR = /\b(src|poster|href|xlink:href)\s*=\s*(['"])(.*?)\2/gi;
+
+function inlineElementSrcs(html, baseDir, ctx) {
+  return replaceMatches(html, SRC_ATTR_TAGS, async ([tag]) => {
+    let out = await replaceMatches(tag, SRC_ATTR, ([, name, , ref]) =>
+      withAsset(ref, baseDir, async abs => {
+        const uri = await toDataUri(abs, ctx);
+        return uri && `${name}="${uri}"`;
+      })
+    );
+    // srcset is a comma-separated candidate list, each entry `url [descriptor]`.
+    const srcset = out.match(/srcset\s*=\s*(['"])(.*?)\1/i);
+    if (srcset) {
+      const parts = await Promise.all(
+        srcset[2].split(',').map(async entry => {
+          const [ref, ...rest] = entry.trim().split(/\s+/);
+          const uri = await withAsset(ref, baseDir, abs => toDataUri(abs, ctx));
+          return uri ? [uri, ...rest].join(' ') : entry.trim();
+        })
+      );
+      out = out.replace(srcset[0], `srcset="${parts.join(', ')}"`);
+    }
+    return out === tag ? null : out;
+  });
+}
+
+/**
+ * Embeds every resolvable local asset an HTML document references.
+ *
+ * @returns {Promise<{ html: string, bytes: number, skipped: Array<{path:string,size:number,reason:string}> }>}
+ */
+async function inlineHtmlAssets(html, absHtmlPath) {
+  const baseDir = path.dirname(absHtmlPath);
+  const ctx = { spent: 0, skipped: [], cache: new Map() };
+  // Author-written <style> blocks first: after inlineStylesheets a <link> has become a
+  // <style> whose refs are already resolved, and re-walking megabytes of data URIs to
+  // find nothing is the one pass worth ordering around.
+  let out = await inlineStyleElements(html, baseDir, ctx);
+  out = await inlineStylesheets(out, baseDir, ctx);
+  out = await inlineScripts(out, baseDir, ctx);
+  out = await inlineElementSrcs(out, baseDir, ctx);
+  return { html: out, bytes: ctx.spent, skipped: ctx.skipped };
+}
+
+module.exports = { inlineHtmlAssets, MAX_ASSET_BYTES };

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 };