threadforge 0.1.0

package/src/core/host-config.js

@@ -0,0 +1,311 @@
+/**
+ * ForgeHost Configuration
+ *
+ * Transforms a multi-project host config into a flat service map
+ * that feeds directly into defineServices(). Each project's services
+ * get namespaced (blog:api), grouped (blog:groupname), and assigned
+ * sequential ports starting from a base port.
+ *
+ * Usage:
+ *
+ *   import { defineHost } from 'threadforge';
+ *
+ *   export default defineHost({
+ *     domain: 'myhost.dev',
+ *     projects: {
+ *       blog: {
+ *         domain: 'blog.myhost.dev',
+ *         config: './projects/blog/forge.config.js',
+ *       },
+ *       gameapi: {
+ *         domain: 'game.myhost.dev',
+ *         config: './projects/gameapi/forge.config.js',
+ *       },
+ *     },
+ *     shared: {
+ *       auth: {
+ *         entry: './shared/auth.js',
+ *         type: 'edge',
+ *         port: 3100,
+ *       },
+ *     },
+ *     plugins: [postgres(), redis()],
+ *   });
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineServices, loadConfig } from "./config.js";
+const BASE_PATH_RE = /^\/[^\s?#]*$/;
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeFrontendConfig(projectId, frontend) {
+  if (!isPlainObject(frontend)) {
+    throw new Error(`Project "${projectId}" frontend must be an object`);
+  }
+
+  if (typeof frontend.plugin !== "string" || frontend.plugin.trim() === "") {
+    throw new Error(`Project "${projectId}" frontend.plugin must be a non-empty string`);
+  }
+  if (typeof frontend.root !== "string" || frontend.root.trim() === "") {
+    throw new Error(`Project "${projectId}" frontend.root must be a non-empty string`);
+  }
+  if (frontend.outDir !== undefined && (typeof frontend.outDir !== "string" || frontend.outDir.trim() === "")) {
+    throw new Error(`Project "${projectId}" frontend.outDir must be a non-empty string when provided`);
+  }
+  if (frontend.basePath !== undefined) {
+    if (typeof frontend.basePath !== "string" || !BASE_PATH_RE.test(frontend.basePath)) {
+      throw new Error(
+        `Project "${projectId}" frontend.basePath must start with "/" and cannot include query strings or fragments`,
+      );
+    }
+  }
+  if (frontend.spaFallback !== undefined && typeof frontend.spaFallback !== "boolean") {
+    throw new Error(`Project "${projectId}" frontend.spaFallback must be a boolean when provided`);
+  }
+  if (frontend.env !== undefined && !isPlainObject(frontend.env)) {
+    throw new Error(`Project "${projectId}" frontend.env must be an object when provided`);
+  }
+  if (frontend.options !== undefined && !isPlainObject(frontend.options)) {
+    throw new Error(`Project "${projectId}" frontend.options must be an object when provided`);
+  }
+
+  return {
+    plugin: frontend.plugin,
+    root: frontend.root,
+    outDir: frontend.outDir ?? `.threadforge/build/${projectId}`,
+    basePath: frontend.basePath ?? "/",
+    spaFallback: frontend.spaFallback ?? true,
+    env: frontend.env ?? {},
+    options: frontend.options ?? {},
+  };
+}
+
+function normalizeProjectDomains(project = {}) {
+  if (Array.isArray(project.domains)) return project.domains;
+  if (typeof project.domain === "string" && project.domain.trim() !== "") return [project.domain];
+  return [];
+}
+
+function validateSiteCollisions(sites) {
+  const seen = new Set();
+  for (const site of Object.values(sites)) {
+    if (site.domains.length === 0) continue;
+    const domains = site.domains;
+    for (const domain of domains) {
+      const key = `${domain}|${site.basePath}`;
+      if (seen.has(key)) {
+        throw new Error(`Duplicate site mapping for domain "${domain}" and basePath "${site.basePath}"`);
+      }
+      seen.add(key);
+    }
+  }
+}
+
+/**
+ * Validate the top-level host config shape.
+ */
+function validateHostConfig(hostConfig) {
+  if (!hostConfig || typeof hostConfig !== "object") {
+    throw new Error("defineHost() requires a host config object");
+  }
+
+  if (!hostConfig.projects || typeof hostConfig.projects !== "object") {
+    throw new Error("defineHost() requires a projects map");
+  }
+
+  const projectIds = Object.keys(hostConfig.projects);
+  if (projectIds.length === 0) {
+    throw new Error("defineHost() requires at least one project");
+  }
+
+  for (const id of projectIds) {
+    if (!/^[a-z][a-z0-9_-]*$/i.test(id)) {
+      throw new Error(
+        `Invalid project ID "${id}": must start with a letter and contain only letters, digits, hyphens, and underscores`,
+      );
+    }
+
+    const project = hostConfig.projects[id];
+    if (!project.config && !project.services) {
+      throw new Error(`Project "${id}" must have either a config path or inline services`);
+    }
+
+    if (project.frontend) {
+      normalizeFrontendConfig(id, project.frontend);
+    }
+  }
+}
+
+/**
+ * Namespace a service map for a project.
+ *
+ * Service names get prefixed: api -> blog:api
+ * Groups get prefixed: core -> blog:core
+ * Connects get prefixed to reference namespaced names.
+ */
+function namespaceServices(projectId, services, sharedServiceNames) {
+  const namespaced = {};
+
+  for (const [name, svc] of Object.entries(services)) {
+    const nsSvc = { ...svc, _projectId: projectId };
+
+    if (nsSvc.group) {
+      nsSvc.group = `${projectId}:${nsSvc.group}`;
+    }
+
+    if (nsSvc.connects) {
+      nsSvc.connects = nsSvc.connects.map((target) => {
+        if (sharedServiceNames.includes(target) || target.includes(":")) return target;
+        return `${projectId}:${target}`;
+      });
+    }
+
+    namespaced[`${projectId}:${name}`] = nsSvc;
+  }
+
+  return namespaced;
+}
+
+/**
+ * Resolve a host config: load each project's config, namespace services,
+ * assign ports, and merge into a flat service map.
+ *
+ * @param {Object} hostConfig - The host config from defineHost()
+ * @returns {Object} A flat services map ready for defineServices()
+ */
+export async function resolveHostConfig(hostConfig) {
+  validateHostConfig(hostConfig);
+
+  let nextPort = hostConfig.basePort ?? 3200;
+  const shared = hostConfig.shared ?? {};
+  const sharedServiceNames = Object.keys(shared);
+  const sites = {};
+
+  const reservedPorts = new Set();
+  const mergedServices = {};
+  for (const [name, svc] of Object.entries(shared)) {
+    if (svc.port) reservedPorts.add(svc.port);
+    mergedServices[name] = { ...svc };
+  }
+
+  const hostMeta = {};
+
+  for (const [projectId, project] of Object.entries(hostConfig.projects)) {
+    let projectServices;
+    if (project.services) {
+      projectServices = project.services;
+    } else {
+      const configPath = path.resolve(process.cwd(), project.config);
+      const configUrl = pathToFileURL(configPath).href;
+      const loaded = await loadConfig(configUrl);
+      projectServices = loaded.services ?? loaded;
+    }
+
+    const namespaced = namespaceServices(projectId, projectServices, sharedServiceNames);
+
+    for (const [nsName, svc] of Object.entries(namespaced)) {
+      if (svc.type === "edge" && !svc.port) {
+        while (reservedPorts.has(nextPort)) nextPort++;
+        svc.port = nextPort;
+        reservedPorts.add(nextPort);
+        nextPort++;
+      }
+
+      if (svc.type === "edge" && sharedServiceNames.includes("auth")) {
+        if (!svc.connects) svc.connects = [];
+        if (!svc.connects.includes("auth")) {
+          svc.connects.push("auth");
+        }
+      }
+
+      mergedServices[nsName] = svc;
+    }
+
+    hostMeta[projectId] = {
+      domain: project.domain ?? null,
+      services: Object.keys(namespaced),
+      schema: project.schema ?? `project_${projectId}`,
+      keyPrefix: `${projectId}:`,
+    };
+
+    const frontend = project.frontend ? normalizeFrontendConfig(projectId, project.frontend) : null;
+    if (frontend && project.static) {
+      console.warn(
+        `[ThreadForge] Project "${projectId}" defines both "frontend" and legacy "static". ` +
+          `Using frontend plugin config and ignoring "static".`,
+      );
+    }
+    sites[projectId] = {
+      siteId: projectId,
+      domains: normalizeProjectDomains(project),
+      basePath: frontend?.basePath ?? "/",
+      services: Object.keys(namespaced),
+      frontend,
+      staticDir: frontend ? null : (project.static ?? null),
+    };
+  }
+
+  validateSiteCollisions(sites);
+
+  return {
+    services: mergedServices,
+    hostMeta,
+    sites,
+    plugins: hostConfig.plugins ?? [],
+    frontendPlugins: hostConfig.frontendPlugins ?? [],
+    domain: hostConfig.domain ?? null,
+    metricsPort: hostConfig.metricsPort ?? 9090,
+  };
+}
+
+/**
+ * Define a multi-project host config.
+ *
+ * Returns a config object marked as host mode that ForgeHost
+ * can process. Can also be resolved immediately for direct use.
+ */
+export function defineHost(hostConfig) {
+  validateHostConfig(hostConfig);
+
+  return {
+    _isHostConfig: true,
+    _raw: hostConfig,
+    domain: hostConfig.domain ?? null,
+    projects: hostConfig.projects,
+    shared: hostConfig.shared ?? {},
+    plugins: hostConfig.plugins ?? [],
+    frontendPlugins: hostConfig.frontendPlugins ?? [],
+    basePort: hostConfig.basePort ?? 3200,
+    metricsPort: hostConfig.metricsPort ?? 9090,
+  };
+}
+
+/**
+ * Resolve a host config and feed it into defineServices().
+ *
+ * @param {Object} hostConfig - Output from defineHost()
+ * @returns {Object} A fully resolved config ready for Supervisor
+ */
+export async function resolveAndDefine(hostConfig) {
+  const raw = hostConfig._isHostConfig ? hostConfig._raw : hostConfig;
+  const resolved = await resolveHostConfig(raw);
+
+  const config = defineServices(resolved.services, {
+    plugins: resolved.plugins,
+    frontendPlugins: resolved.frontendPlugins,
+    sites: resolved.sites,
+    metricsPort: resolved.metricsPort,
+  });
+
+  // Mark as host mode for downstream consumers
+  config._isHostMode = true;
+  config._hostMeta = resolved.hostMeta;
+  config._hostDomain = resolved.domain;
+  config._sites = resolved.sites;
+
+  return config;
+}

package/src/core/network-utils.js

@@ -0,0 +1,166 @@
+/**
+ * Network utility functions for ThreadForge.
+ *
+ * Extracted from ForgeContext.js (A10) so other modules can reuse
+ * isPrivateNetwork, matchCIDR, ipToInt, and isTrustedProxy without
+ * pulling in the full ForgeContext dependency graph.
+ */
+
+// P12: Cache parsed FORGE_TRUSTED_NETWORKS — re-parse only when the env var changes
+let _trustedNetworksRaw = undefined;
+let _trustedNetworksParsed = [];
+let _ipv6Warned = false;
+
+function _getTrustedNetworks() {
+  const raw = process.env.FORGE_TRUSTED_NETWORKS;
+  if (raw === _trustedNetworksRaw) return _trustedNetworksParsed;
+  _trustedNetworksRaw = raw;
+  if (!raw) {
+    _trustedNetworksParsed = [];
+    return _trustedNetworksParsed;
+  }
+  const result = [];
+  for (const cidr of raw.split(",")) {
+    const trimmed = cidr.trim();
+    if (!trimmed) continue;
+    if (trimmed.includes(":")) {
+      if (!_ipv6Warned) {
+        _ipv6Warned = true;
+        process.stderr.write(
+          JSON.stringify({
+            timestamp: new Date().toISOString(),
+            level: "warn",
+            message: `FORGE_TRUSTED_NETWORKS contains IPv6 entry "${trimmed}" which is not supported. Only IPv4 CIDRs are supported.`,
+          }) + "\n"
+        );
+      }
+      continue;
+    }
+    result.push(trimmed);
+  }
+  _trustedNetworksParsed = result;
+  return result;
+}
+
+/**
+ * Convert an IPv4 dotted-quad string to a 32-bit unsigned integer.
+ * Returns null if the address is malformed.
+ * @param {string} ip
+ * @returns {number|null}
+ */
+export function ipToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let result = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (Number.isNaN(n) || n < 0 || n > 255) return null;
+    result = (result << 8) | n;
+  }
+  return result >>> 0;
+}
+
+/**
+ * Basic CIDR match for IPv4. Matches address against prefix/length.
+ * @param {string} addr - IPv4 address
+ * @param {string} cidr - CIDR notation (e.g., "10.0.0.0/8")
+ * @returns {boolean}
+ */
+export function matchCIDR(addr, cidr) {
+  const [prefix, lenStr] = cidr.split("/");
+  if (!prefix || !lenStr) return false;
+
+  const maskLen = parseInt(lenStr, 10);
+  if (Number.isNaN(maskLen) || maskLen < 0 || maskLen > 32) return false;
+
+  const addrNum = ipToInt(addr);
+  const prefixNum = ipToInt(prefix);
+  if (addrNum === null || prefixNum === null) return false;
+
+  const mask = maskLen === 0 ? 0 : (~0 << (32 - maskLen)) >>> 0;
+  return (addrNum & mask) === (prefixNum & mask);
+}
+
+/**
+ * Normalize a raw socket address by stripping IPv6 zone IDs and
+ * IPv6-mapped IPv4 prefixes.
+ * @param {string} address
+ * @returns {string}
+ */
+export function normalizeAddress(address) {
+  // Strip IPv6 zone ID suffix (e.g., %eth0)
+  const noZone = address.split("%")[0];
+  // S5: Tighten IPv6-mapped IPv4 regex — require exactly 5 zero groups before ffff:
+  // Matches forms like 0:0:0:0:0:ffff:x.x.x.x or 0000:0000:0000:0000:0000:ffff:x.x.x.x
+  return noZone
+    .toLowerCase()
+    .replace(/^(?:0{1,4}:){5}(?:0{1,4}:)?ffff:/, "")
+    .replace(/^::ffff:/, "");
+}
+
+/**
+ * Check if a remote address is from a private/trusted network.
+ *
+ * Covers RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16),
+ * loopback (127.0.0.0/8, ::1), IPv6-mapped IPv4 (::ffff:x.x.x.x),
+ * and custom trusted networks via FORGE_TRUSTED_NETWORKS env var.
+ *
+ * @param {string} address - Remote socket address
+ * @returns {boolean}
+ */
+export function isPrivateNetwork(address) {
+  if (!address) return false;
+
+  const addr = normalizeAddress(address);
+
+  // Loopback
+  if (addr === "127.0.0.1" || addr === "::1" || addr.startsWith("127.")) return true;
+
+  // IPv6 link-local (fe80::/10)
+  if (/^fe[89ab][0-9a-f]:/i.test(addr)) return true;
+
+  // IPv6 unique local (fc00::/7)
+  if (/^f[cd][0-9a-f]{2}:/i.test(addr)) return true;
+
+  // RFC 1918 private ranges
+  if (addr.startsWith("10.")) return true;
+  if (addr.startsWith("192.168.")) return true;
+
+  // 172.16.0.0/12 — covers 172.16.x.x through 172.31.x.x
+  if (addr.startsWith("172.")) {
+    const second = parseInt(addr.split(".")[1], 10);
+    if (second >= 16 && second <= 31) return true;
+  }
+
+  // Link-local (169.254.0.0/16)
+  if (addr.startsWith("169.254.")) return true;
+
+  // P12: Use cached trusted networks (re-parsed only when env var changes)
+  for (const cidr of _getTrustedNetworks()) {
+    if (matchCIDR(addr, cidr)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if a remote address is a trusted proxy.
+ * Only trusts addresses listed in FORGE_TRUSTED_PROXIES env var.
+ * @param {string} address
+ * @returns {boolean}
+ */
+export function isTrustedProxy(address) {
+  const trusted = process.env.FORGE_TRUSTED_PROXIES;
+  if (!trusted) return false;
+  if (!address) return false;
+  const addr = normalizeAddress(address);
+  for (const entry of trusted.split(",")) {
+    const trimmed = entry.trim();
+    if (trimmed.includes("/")) {
+      if (matchCIDR(addr, trimmed)) return true;
+    } else if (addr === trimmed) {
+      return true;
+    }
+  }
+  return false;
+}