@tridha643/hestia 1.0.0

package/dist/assets/portless/dist/index.d.ts

@@ -0,0 +1,222 @@
+import * as node_tls from 'node:tls';
+import * as http from 'node:http';
+import * as net from 'node:net';
+
+/** Route info used by the proxy server to map hostnames to ports. */
+interface RouteInfo {
+    hostname: string;
+    port: number;
+}
+interface ProxyServerOptions {
+    /** Called on each request to get the current route table. */
+    getRoutes: () => RouteInfo[];
+    /** The port the proxy is listening on (used to build correct URLs). */
+    proxyPort: number;
+    /** TLD suffix used for hostnames (default: "localhost"). */
+    tld?: string;
+    /** All TLD suffixes used for hostnames. The first one is used for examples. */
+    tlds?: string[];
+    /**
+     * When true, only exact hostname matches are used. Unregistered subdomain
+     * prefixes return 404 instead of falling back to the base service.
+     * Defaults to true.
+     */
+    strict?: boolean;
+    /** Optional error logger; defaults to console.error. */
+    onError?: (message: string) => void;
+    /** When provided, enables HTTP/2 over TLS (HTTPS). */
+    tls?: {
+        cert: Buffer;
+        key: Buffer;
+        /** CA certificate to include in the chain so clients can verify the leaf. */
+        ca?: Buffer;
+        /** SNI callback for per-hostname certificate selection. */
+        SNICallback?: (servername: string, cb: (err: Error | null, ctx?: node_tls.SecureContext) => void) => void;
+    };
+}
+
+/** Response header used to identify a portless proxy (for health checks). */
+declare const PORTLESS_HEADER = "X-Portless";
+/** Server type returned by createProxyServer (plain HTTP/1.1 or net.Server TLS wrapper). */
+type ProxyServer = http.Server | net.Server;
+/**
+ * Create an HTTP proxy server that routes requests based on the Host header.
+ *
+ * Uses Node's built-in http module for proxying (no external dependencies).
+ * The `getRoutes` callback is invoked on every request so callers can provide
+ * either a static list or a live-updating one.
+ *
+ * When `tls` is provided, creates an HTTP/2 secure server with HTTP/1.1
+ * fallback (`allowHTTP1: true`). This enables HTTP/2 multiplexing for
+ * browsers while keeping WebSocket upgrades working over HTTP/1.1.
+ */
+declare function createProxyServer(options: ProxyServerOptions): ProxyServer;
+/**
+ * Create a minimal HTTP server that 302-redirects every request to HTTPS.
+ * Meant to run on port 80 alongside an HTTPS proxy on port 443.
+ */
+declare function createHttpRedirectServer(httpsPort: number): http.Server;
+
+/** File permission mode for route and state files. */
+declare const FILE_MODE = 420;
+/** Directory permission mode for the state directory. */
+declare const DIR_MODE = 493;
+interface RouteMapping extends RouteInfo {
+    pid: number;
+    tailscaleUrl?: string;
+    tailscaleHttpsPort?: number;
+    tailscaleFunnel?: boolean;
+    ngrokUrl?: string;
+    ngrokPid?: number;
+}
+type RouteMetadataPatch = {
+    tailscaleUrl?: string | null;
+    tailscaleHttpsPort?: number | null;
+    tailscaleFunnel?: boolean | null;
+    ngrokUrl?: string | null;
+    ngrokPid?: number | null;
+};
+/**
+ * Thrown when a route is already registered by a live process and --force was
+ * not specified. With --force, the existing process is killed instead.
+ */
+declare class RouteConflictError extends Error {
+    readonly hostname: string;
+    readonly existingPid: number;
+    constructor(hostname: string, existingPid: number);
+}
+/**
+ * Manages route mappings stored as a JSON file on disk.
+ * Supports file locking and stale-route cleanup.
+ */
+declare class RouteStore {
+    /** The state directory path. */
+    readonly dir: string;
+    private readonly routesPath;
+    private readonly lockPath;
+    readonly pidPath: string;
+    readonly portFilePath: string;
+    private readonly onWarning;
+    constructor(dir: string, options?: {
+        onWarning?: (message: string) => void;
+    });
+    ensureDir(): void;
+    getRoutesPath(): string;
+    private static readonly sleepBuffer;
+    private syncSleep;
+    private acquireLock;
+    private releaseLock;
+    private isProcessAlive;
+    /**
+     * Load routes from disk, filtering out stale entries whose owning process
+     * is no longer alive. Stale-route cleanup is only persisted when the caller
+     * already holds the lock (i.e. inside addRoute/removeRoute) to avoid
+     * unprotected concurrent writes.
+     */
+    loadRoutes(persistCleanup?: boolean): RouteMapping[];
+    private saveRoutes;
+    /**
+     * Register a route. When `force` is true and the hostname is already claimed
+     * by another live process, that process is sent SIGTERM before the route is
+     * replaced. Returns the PID of the killed process (if any) so the caller can
+     * log it.
+     */
+    addRoute(hostname: string, port: number, pid: number, force?: boolean): number | undefined;
+    /**
+     * Load all routes from disk without filtering out dead PIDs. Used by
+     * `portless prune` to discover stale entries whose owning CLI is gone
+     * but whose dev server may still be holding a port.
+     */
+    loadRoutesRaw(): RouteMapping[];
+    /**
+     * Remove all route entries whose owning process is dead and persist the
+     * result. Returns the removed stale entries so the caller can act on them.
+     */
+    pruneStaleRoutes(): RouteMapping[];
+    /**
+     * Update metadata on an existing route entry. Only provided fields are
+     * merged; the route must already exist (matched by hostname).
+     */
+    updateRoute(hostname: string, fields: RouteMetadataPatch): void;
+    /**
+     * Remove a route by hostname. When `ownerPid` is provided, the entry is
+     * only removed while it is still owned by that pid. Exit cleanups must
+     * pass their own pid: after a `--force` takeover the killed process would
+     * otherwise deregister the route the new owner just registered.
+     */
+    removeRoute(hostname: string, ownerPid?: number): void;
+}
+
+/**
+ * When running under sudo, fix file ownership so the real user can
+ * read/write the file later without sudo. No-op on Windows or when not
+ * running as root.
+ */
+declare function fixOwnership(...paths: string[]): void;
+/** Type guard for Node.js system errors with an error code. */
+declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
+/** Return whether a process exists, treating permission denial as alive. */
+declare function isProcessAlive(pid: number): boolean;
+/**
+ * Escape HTML special characters to prevent XSS.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Format a URL for the given hostname. Omits the port when it matches the
+ * protocol default (80 for HTTP, 443 for HTTPS).
+ */
+declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
+/**
+ * Parse and normalize a hostname input for use as a subdomain of the
+ * configured TLD. Strips protocol prefixes, validates characters, and
+ * appends the TLD suffix if needed.
+ */
+declare function parseHostname(input: string, tld?: string): string;
+/**
+ * Parse a hostname input for every configured TLD. If the input already ends
+ * with one of those TLDs, use the stripped base name for the full set.
+ */
+declare function parseHostnames(input: string, tlds?: readonly string[]): string[];
+
+/**
+ * Extract the portless-managed block from /etc/hosts content.
+ * Returns the lines between the markers (exclusive), or an empty array
+ * if no managed block exists.
+ */
+declare function extractManagedBlock(content: string): string[];
+/**
+ * Remove the portless-managed block from /etc/hosts content and return
+ * the cleaned content with trailing newlines normalized.
+ */
+declare function removeBlock(content: string): string;
+/**
+ * Build a portless-managed block for the given hostnames.
+ */
+declare function buildBlock(hostnames: string[]): string;
+/**
+ * Whether the proxy should write route hostnames to the hosts file.
+ * Disabled only when `PORTLESS_SYNC_HOSTS` is `0` or `false` (opt-out).
+ */
+declare function shouldAutoSyncHosts(syncVal: string | undefined): boolean;
+/**
+ * Sync /etc/hosts to include entries for all given hostnames.
+ * Replaces any existing portless-managed block. Requires root access.
+ * Returns true on success, false on failure.
+ */
+declare function syncHostsFile(hostnames: string[]): boolean;
+/**
+ * Remove the portless-managed block from /etc/hosts.
+ * Returns true on success, false on failure.
+ */
+declare function cleanHostsFile(): boolean;
+/**
+ * Return the current portless-managed hostnames from /etc/hosts.
+ */
+declare function getManagedHostnames(): string[];
+/**
+ * Check whether a hostname resolves to 127.0.0.1 via the system DNS resolver.
+ * Returns true if resolution works, false otherwise.
+ */
+declare function checkHostResolution(hostname: string): Promise<boolean>;
+
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, isProcessAlive, parseHostname, parseHostnames, removeBlock, shouldAutoSyncHosts, syncHostsFile };

package/dist/assets/portless/dist/index.js

@@ -0,0 +1,48 @@
+import {
+  DIR_MODE,
+  FILE_MODE,
+  PORTLESS_HEADER,
+  RouteConflictError,
+  RouteStore,
+  buildBlock,
+  checkHostResolution,
+  cleanHostsFile,
+  createHttpRedirectServer,
+  createProxyServer,
+  escapeHtml,
+  extractManagedBlock,
+  fixOwnership,
+  formatUrl,
+  getManagedHostnames,
+  isErrnoException,
+  isProcessAlive,
+  parseHostname,
+  parseHostnames,
+  removeBlock,
+  shouldAutoSyncHosts,
+  syncHostsFile
+} from "./chunk-SD2PIWJU.js";
+export {
+  DIR_MODE,
+  FILE_MODE,
+  PORTLESS_HEADER,
+  RouteConflictError,
+  RouteStore,
+  buildBlock,
+  checkHostResolution,
+  cleanHostsFile,
+  createHttpRedirectServer,
+  createProxyServer,
+  escapeHtml,
+  extractManagedBlock,
+  fixOwnership,
+  formatUrl,
+  getManagedHostnames,
+  isErrnoException,
+  isProcessAlive,
+  parseHostname,
+  parseHostnames,
+  removeBlock,
+  shouldAutoSyncHosts,
+  syncHostsFile
+};

package/dist/assets/portless/hestia-hardening.patch

@@ -0,0 +1,177 @@
+diff --git a/dist/cli.js b/dist/cli.js
+--- a/dist/cli.js
++++ b/dist/cli.js
+@@ -2867,7 +2867,12 @@
+ var SYSTEMD_SERVICE = "portless.service";
+ var WINDOWS_TASK_NAME = "Portless Proxy";
+ var INTERNAL_ELEVATED_ENV = "PORTLESS_INTERNAL_SERVICE_ELEVATED";
+-var SERVICE_ENV_KEYS = /* @__PURE__ */ new Set(["PORTLESS_SYNC_HOSTS"]);
++var SERVICE_ENV_KEYS = /* @__PURE__ */ new Set([
++  "PORTLESS_SYNC_HOSTS",
++  "HESTIA_PORTLESS_ROUTES_PATH",
++  "HESTIA_PORTLESS_ROOT_STATE",
++  "HESTIA_PORTLESS_ROUTES_UID"
++]);
+ function normalizeTlds(tlds) {
+   return [...new Set(tlds.length > 0 ? tlds : [DEFAULT_TLD])];
+ }
+@@ -4067,9 +4072,86 @@
+   } catch {
+   }
+   fixOwnership(routesPath);
+-  let cachedRoutes = store.loadRoutes();
++  const externalRoutesPath = process.env.HESTIA_PORTLESS_ROUTES_PATH;
++  const loadExternalRoutes = () => {
++    if (!externalRoutesPath) return [];
++    let fd;
++    try {
++      fd = fs9.openSync(
++        externalRoutesPath,
++        fs9.constants.O_RDONLY | (fs9.constants.O_NOFOLLOW ?? 0)
++      );
++      const stat = fs9.fstatSync(fd);
++      const expectedUid = Number(process.env.HESTIA_PORTLESS_ROUTES_UID);
++      if (!stat.isFile() || stat.size > 1024 * 1024 || !Number.isInteger(expectedUid) || stat.uid !== expectedUid) {
++        return [];
++      }
++      const parsed = JSON.parse(fs9.readFileSync(fd, "utf8"));
++      if (!Array.isArray(parsed)) return [];
++      return parsed.filter((route) =>
++        typeof route === "object" && route !== null &&
++        typeof route.hostname === "string" &&
++        route.hostname.endsWith(".localhost") && route.hostname.length <= 253 &&
++        route.hostname.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) &&
++        Number.isInteger(route.port) && route.port > 0 && route.port <= 65535 &&
++        Number.isInteger(route.pid) && route.pid > 0 &&
++        typeof route.startTime === "string" && route.startTime.length > 0 && route.startTime.length <= 128
++      );
++    } catch {
++      return [];
++    } finally {
++      if (fd !== void 0) fs9.closeSync(fd);
++    }
++  };
++  const loadAllRoutes = () => {
++    const externalRoutes = loadExternalRoutes();
++    const externalHostnames = new Set(externalRoutes.map((route) => route.hostname));
++    return [
++      ...store.loadRoutes().filter((route) => !externalHostnames.has(route.hostname)),
++      ...externalRoutes
++    ];
++  };
++  let cachedRoutes = loadAllRoutes();
++  let liveRouteIdentities = /* @__PURE__ */ new Set();
++  const routeIdentityKey = (route) => `${route.pid}\0${route.startTime}`;
++  const refreshRouteIdentities = () => {
++    const guardedRoutes = cachedRoutes.filter((route) => typeof route.startTime === "string");
++    if (guardedRoutes.length === 0) {
++      liveRouteIdentities = /* @__PURE__ */ new Set();
++      return;
++    }
++    try {
++      const pids = [...new Set(guardedRoutes.map((route) => route.pid))];
++      const output = execFileSync("ps", ["-p", pids.join(","), "-o", "pid=,lstart="], {
++        encoding: "utf8",
++        timeout: 1e3,
++        env: { ...process.env, LC_ALL: "C", LANG: "C" }
++      });
++      const identities = /* @__PURE__ */ new Set();
++      for (const line of output.split("\n")) {
++        const match = line.match(/^\s*(\d+)\s+(.+)$/);
++        if (match) identities.add(`${Number(match[1])}\0${match[2].trim()}`);
++      }
++      liveRouteIdentities = identities;
++    } catch {
++      liveRouteIdentities = /* @__PURE__ */ new Set();
++    }
++  };
++  const routeProcessIsAlive = (route) => {
++    if (route.pid === 0) return true;
++    try {
++      process.kill(route.pid, 0);
++    } catch {
++      return false;
++    }
++    return typeof route.startTime !== "string" || liveRouteIdentities.has(routeIdentityKey(route));
++  };
++  refreshRouteIdentities();
++  const identityRefreshInterval = setInterval(refreshRouteIdentities, 500);
++  identityRefreshInterval.unref();
+   let debounceTimer = null;
+   let watcher = null;
++  let externalWatcher = null;
+   let pollingInterval = null;
+   const autoSyncHosts = shouldAutoSyncHosts(process.env.PORTLESS_SYNC_HOSTS);
+   const onMdnsError = (msg) => console.warn(chalk.yellow(msg));
+@@ -4098,7 +4180,8 @@
+   const reloadRoutes = () => {
+     try {
+       const previousRoutes = new Map(cachedRoutes.map((r) => [r.hostname, r.port]));
+-      cachedRoutes = store.loadRoutes();
++      cachedRoutes = loadAllRoutes();
++      refreshRouteIdentities();
+       if (autoSyncHosts) {
+         syncHostsFile(cachedRoutes.map((r) => r.hostname));
+       }
+@@ -4131,12 +4214,24 @@
+     console.warn(colors_default.yellow("fs.watch unavailable; falling back to polling for route changes"));
+     pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);
+   }
++  if (externalRoutesPath) {
++    try {
++      const externalBasename = path9.basename(externalRoutesPath);
++      externalWatcher = fs9.watch(path9.dirname(externalRoutesPath), (_event, filename) => {
++        if (filename && filename.toString() !== externalBasename) return;
++        if (debounceTimer) clearTimeout(debounceTimer);
++        debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
++      });
++    } catch {
++      if (!pollingInterval) pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);
++    }
++  }
+   if (autoSyncHosts) {
+     syncHostsFile(cachedRoutes.map((r) => r.hostname));
+   }
+   publishCachedRoutes();
+   const server = createProxyServer({
+-    getRoutes: () => cachedRoutes,
++    getRoutes: () => cachedRoutes.filter(routeProcessIsAlive),
+     proxyPort,
+     tld,
+     tlds,
+@@ -4171,9 +4266,9 @@
+     redirectServer.on("error", () => {
+       redirectServer = null;
+     });
+-    redirectServer.listen(80);
++    redirectServer.listen(80, "127.0.0.1");
+   }
+-  server.listen(proxyPort, () => {
++  server.listen(proxyPort, "127.0.0.1", () => {
+     fs9.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+     fs9.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+     writeTlsMarker(store.dir, isTls);
+@@ -4215,10 +4310,12 @@
+     exiting = true;
+     if (debounceTimer) clearTimeout(debounceTimer);
+     if (pollingInterval) clearInterval(pollingInterval);
++    clearInterval(identityRefreshInterval);
+     if (lanMonitor) lanMonitor.stop();
+     if (watcher) {
+       watcher.close();
+     }
++    if (externalWatcher) externalWatcher.close();
+     if (activeLanIp) cleanupAll();
+     if (redirectServer) {
+       redirectServer.close();
+diff --git a/dist/chunk-SD2PIWJU.js b/dist/chunk-SD2PIWJU.js
+--- a/dist/chunk-SD2PIWJU.js
++++ b/dist/chunk-SD2PIWJU.js
+@@ -2,6 +2,7 @@
+ import * as fs from "fs";
+ function fixOwnership(...paths) {
+   if (process.platform === "win32") return;
++  if (process.env.HESTIA_PORTLESS_ROOT_STATE === "1") return;
+   const uid = process.env.SUDO_UID;
+   const gid = process.env.SUDO_GID;
+   if (!uid || process.getuid?.() !== 0) return;

package/dist/assets/portless/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "portless",
+  "version": "0.15.1",
+  "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "portless": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prepublishOnly": "cp ../../README.md . && pnpm build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "local",
+    "development",
+    "proxy",
+    "localhost"
+  ],
+  "author": "Vercel Labs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel-labs/portless.git"
+  },
+  "homepage": "https://portless.sh",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/portless/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  }
+}

package/dist/assets/portless/provenance.json

@@ -0,0 +1,5 @@
+{
+  "package": "portless",
+  "version": "0.15.1",
+  "patchSha256": "9ca94ca771ce502769a2c7cbe3bb4fe8d54dc847ff9f7e3e2b34abf728618690"
+}