@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/runtime/Proxy.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayProxy = void 0;
+exports.forwardedFromOutside = forwardedFromOutside;
 const http_proxy_1 = __importDefault(require("http-proxy"));
 const http_1 = __importDefault(require("http"));
+const node_net_1 = require("node:net");
 const global_logger_factory_1 = require("global-logger-factory");
 const NodeRuntimeHost_1 = require("./host/node/NodeRuntimeHost");
 const GatewayAdminProxyAuth_1 = require("./GatewayAdminProxyAuth");
@@ -214,15 +216,15 @@ class GatewayProxy {
         const pathname = url.split('?')[0];
         const origin = req.headers.origin;
         const originalRemoteAddress = this.clientRemoteAddressResolver?.(req) ?? req.socket.remoteAddress;
-        // A loopback peer address only proves the connection came from this machine. Managed
-        // tunnels and the P2P data plane terminate here too, so anything that arrived through
-        // a remote forwarding path is never local, whatever its peer address or headers say.
-        const originalClientLoopback = !untrustedIngress && (0, GatewayAdminProxyAuth_1.isLoopbackRemoteAddress)(originalRemoteAddress);
-        const internalPodProxyHeaders = this.verifiedInternalPodProxyHeaders(req, originalClientLoopback);
+        // A loopback peer address only proves the connection came from this machine: tunnels and
+        // the P2P data plane terminate here too. Forwarded-for is what separates them - a local
+        // dev proxy forwards this machine's address, while a provider edge appends the address it
+        // saw, so a request whose right-most forwarder is not loopback came from outside and is
+        // never local, whatever its peer address or headers say.
+        const originalClientLoopback = !untrustedIngress
+            && !forwardedFromOutside(req)
+            && (0, GatewayAdminProxyAuth_1.isLoopbackRemoteAddress)(originalRemoteAddress);
         (0, GatewayAdminProxyAuth_1.stripGatewayAdminProxyHeaders)(req.headers);
-        if (internalPodProxyHeaders) {
-            Object.assign(req.headers, internalPodProxyHeaders);
-        }
         // Store public host for routing before any CSS canonical-host rewrites.
         // External gateways pass the original domain through X-Forwarded-Host;
         // direct/local requests use Host.
@@ -302,7 +304,7 @@ class GatewayProxy {
             if (origin) {
                 this.addCorsHeaders(res, origin);
             }
-            void this.handleInternalApi(req, res);
+            void this.handleInternalApi(req, res, this.hasOperatorAuthority(req, originalClientLoopback));
             return;
         }
         // 2. API Server Routing.
@@ -387,24 +389,6 @@ class GatewayProxy {
             originalClientLoopback,
         }));
     }
-    verifiedInternalPodProxyHeaders(req, originalClientLoopback) {
-        if (!originalClientLoopback || req.url !== '/.internal/pod-data') {
-            return undefined;
-        }
-        const verification = (0, GatewayAdminProxyAuth_1.verifyGatewayAdminProxyHeaders)({
-            headers: req.headers,
-            secret: this.internalAdminAuthSecret,
-            method: req.method,
-            url: req.url,
-        });
-        if (!verification.valid || !verification.originalClientLoopback || !verification.intent || !verification.nonce) {
-            return undefined;
-        }
-        return Object.fromEntries(GatewayAdminProxyAuth_1.GATEWAY_ADMIN_PROXY_HEADERS.flatMap((header) => {
-            const value = req.headers[header];
-            return value === undefined ? [] : [[header, value]];
-        }));
-    }
     isApiHost(hostHeader) {
         const host = this.normalizeHost(hostHeader);
         if (!host) {
@@ -579,20 +563,51 @@ class GatewayProxy {
         res.setHeader('Access-Control-Allow-Headers', CORS_CONFIG.allowedHeaders.join(', '));
         res.setHeader('Access-Control-Expose-Headers', CORS_CONFIG.exposedHeaders.join(', '));
     }
-    async handleInternalApi(req, res) {
+    /**
+     * Whether this request carries operator authority.
+     *
+     * `/service/*` exposes logs and service control, so a caller that only reached the Gateway
+     * through a tunnel must not get it - whatever address it presents. A local caller counts, and
+     * so does a signed gateway admin proxy header, which is how the same machine proves it is the
+     * operator through a local forwarder.
+     */
+    hasOperatorAuthority(req, originalClientLoopback) {
+        if (originalClientLoopback) {
+            return true;
+        }
+        if (!this.internalAdminAuthSecret) {
+            return false;
+        }
+        const verification = (0, GatewayAdminProxyAuth_1.verifyGatewayAdminProxyHeaders)({
+            headers: req.headers,
+            secret: this.internalAdminAuthSecret,
+            method: req.method,
+            url: req.url,
+        });
+        return verification.valid;
+    }
+    async handleInternalApi(req, res, operatorAuthorized) {
         try {
             const reqUrl = req.url ?? '/';
             const parsed = new URL(reqUrl, 'http://localhost');
             const pathname = parsed.pathname;
+            // Status is the entry probe every client uses, and it carries no secrets.
             if (pathname === '/service/status') {
                 const status = this.supervisor.getAllStatus();
-                const cssReady = await this.isCssReady();
-                const code = cssReady ? 200 : 503;
+                // Readiness must cover every supervised child, not just CSS: a gateway whose API child
+                // crashed and gave up used to answer 200 here for hours while /api/* returned 502 (N20).
+                const servicesReady = this.supervisor.isReady();
+                const cssReady = servicesReady && await this.isCssReady();
+                const code = servicesReady && cssReady ? 200 : 503;
                 res.writeHead(code, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify(status));
                 return;
             }
             if (pathname === '/service/logs') {
+                if (!operatorAuthorized) {
+                    sendOperatorRequired(res);
+                    return;
+                }
                 const level = parsed.searchParams.get('level') ?? undefined;
                 const source = parsed.searchParams.get('source') ?? undefined;
                 const limitValue = parsed.searchParams.get('limit');
@@ -608,6 +623,10 @@ class GatewayProxy {
             }
             const restartMatch = /^\/service\/restart\/([^/]+)$/.exec(pathname);
             if (restartMatch && req.method === 'POST') {
+                if (!operatorAuthorized) {
+                    sendOperatorRequired(res);
+                    return;
+                }
                 const service = decodeURIComponent(restartMatch[1]);
                 if (service === 'gateway') {
                     res.writeHead(409, { 'Content-Type': 'application/json' });
@@ -630,6 +649,10 @@ class GatewayProxy {
                 return;
             }
             if (pathname === '/service/stop' && req.method === 'POST') {
+                if (!operatorAuthorized) {
+                    sendOperatorRequired(res);
+                    return;
+                }
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ ok: true }));
                 setImmediate(() => {
@@ -682,4 +705,51 @@ exports.GatewayProxy = GatewayProxy;
 function isBunRuntime() {
     return typeof globalThis.Bun !== 'undefined';
 }
+/**
+ * Whether the client-address headers say this request travelled through a forwarder outside
+ * this machine.
+ *
+ * This is the fallback behind the structural gate (the Gateway's tunnel entry listener): a
+ * tunnel pointed at the Gateway port by mistake still must not inherit local trust. Only
+ * headers that carry a client *address* count - `x-forwarded-for`, `x-real-ip` and the
+ * `for=` part of `Forwarded`. `x-forwarded-host`/`x-forwarded-proto` do not: a local dev proxy
+ * sets them for local browsers too, so treating them as evidence would lock the operator out
+ * of their own admin surface.
+ *
+ * The right-most value is the address the last forwarder saw - the one our own handlers append
+ * (`ClusterIngressRouter`, `EdgeNodeProxyHttpHandler`, `PodRoutingHttpHandler`) - so a client
+ * cannot look local by sending its own. An unreadable value is treated as remote.
+ */
+/** Service control and logs are for the operator, not for whoever reached the entry. */
+function sendOperatorRequired(res) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Operator access required' }));
+}
+function forwardedFromOutside(req) {
+    const evidence = [
+        ...splitHeaderList(req.headers['x-forwarded-for']),
+        ...splitHeaderList(req.headers['x-real-ip']),
+        ...forwardedForParameters(req.headers.forwarded),
+    ];
+    const last = evidence.at(-1);
+    if (last === undefined) {
+        return false;
+    }
+    return (0, node_net_1.isIP)(last) === 0 || !(0, GatewayAdminProxyAuth_1.isLoopbackRemoteAddress)(last);
+}
+function splitHeaderList(raw) {
+    const value = Array.isArray(raw) ? raw.join(',') : raw;
+    return value?.split(',').map((entry) => entry.trim()).filter(Boolean) ?? [];
+}
+/** The `for=` values of an RFC 7239 `Forwarded` header, in order. */
+function forwardedForParameters(raw) {
+    const value = Array.isArray(raw) ? raw.join(',') : raw;
+    if (!value) {
+        return [];
+    }
+    return value.split(/[;,]/u)
+        .map((part) => /^\s*for\s*=\s*(.+)$/iu.exec(part.trim())?.[1])
+        .filter((entry) => Boolean(entry))
+        .map((entry) => entry.replace(/^"|"$/gu, '').replace(/^\[|\]$/gu, ''));
+}
 //# sourceMappingURL=Proxy.js.map

package/dist/runtime/bootstrap.d.ts

@@ -25,6 +25,16 @@ export interface RuntimeBootstrapState {
     ports: XpodRuntimePorts;
     sockets: XpodRuntimeSockets;
 }
+/**
+ * Address that a co-located runtime service must be reached on when it was bound
+ * to `bindHost`. Wildcard binds are not connectable on every platform, so they
+ * map to their loopback counterpart; any other value (including a hostname such
+ * as `localhost`, which may resolve to IPv6 only) is used as-is, because the
+ * gateway must connect to the very address the service actually bound.
+ */
+export declare function connectHostForBindHost(bindHost?: string): string;
+/** Loopback URL for a runtime service bound to `bindHost`. */
+export declare function localServiceUrl(bindHost: string | undefined, port: number): string;
 export declare function cssAuthModeConfigImports(authMode: AuthMode): string[];
 export declare function resolveRuntimeBootstrap(id: string, options: XpodRuntimeOptions, host: RuntimeHost, platform?: RuntimePlatform): Promise<RuntimeBootstrapState>;
 export declare function buildRuntimeEnv(state: RuntimeBootstrapState, options: XpodRuntimeOptions, envFromFile?: Record<string, string | undefined>): Record<string, string | undefined>;

package/dist/runtime/bootstrap.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectHostForBindHost = connectHostForBindHost;
+exports.localServiceUrl = localServiceUrl;
 exports.cssAuthModeConfigImports = cssAuthModeConfigImports;
 exports.resolveRuntimeBootstrap = resolveRuntimeBootstrap;
 exports.buildRuntimeEnv = buildRuntimeEnv;
@@ -35,6 +37,28 @@ function ensureTrailingSlash(url) {
 function publicHostForBindHost(bindHost) {
     return bindHost === '127.0.0.1' || bindHost === '::1' ? 'localhost' : bindHost;
 }
+/**
+ * Address that a co-located runtime service must be reached on when it was bound
+ * to `bindHost`. Wildcard binds are not connectable on every platform, so they
+ * map to their loopback counterpart; any other value (including a hostname such
+ * as `localhost`, which may resolve to IPv6 only) is used as-is, because the
+ * gateway must connect to the very address the service actually bound.
+ */
+function connectHostForBindHost(bindHost) {
+    const host = bindHost ?? '127.0.0.1';
+    if (host === '0.0.0.0') {
+        return '127.0.0.1';
+    }
+    if (host === '::' || host === '[::]' || host === '::0') {
+        return '::1';
+    }
+    return host;
+}
+/** Loopback URL for a runtime service bound to `bindHost`. */
+function localServiceUrl(bindHost, port) {
+    const host = connectHostForBindHost(bindHost);
+    return `http://${host.includes(':') ? `[${host}]` : host}:${port}`;
+}
 function normalizeWindowsAbsolutePath(filePath) {
     return filePath.replace(/^[\\/]+(?=[A-Za-z]:[\\/])/, '');
 }

package/dist/runtime/css-process.d.ts

@@ -6,13 +6,13 @@ import type { AuthMode } from '../authorization/AuthMode';
  * The legacy CSS child process path injects it through a generated
  * Components.js config instead of CSS_* env aliases.
  */
-export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: NodeJS.ProcessEnv, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
+export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: Record<string, string | undefined>, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
 export declare function createCssChildRuntimeConfig(options: {
     configPath: string;
     runtimeRoot: string;
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): {
     configPath: string;
     cwd?: string;
@@ -36,5 +36,5 @@ export declare function buildApiChildEnv(options: {
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
     gatewayAdminProxyAuthSecret?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): Record<string, string>;

package/dist/runtime/host/node/NodeRuntimeHost.js

@@ -23,9 +23,11 @@ class NodeRuntimeHost {
         const gateway = options.gatewayPort ?? await (0, port_finder_1.getFreePort)(options.basePort ?? 5600);
         const css = options.cssPort ?? await (0, port_finder_1.getFreePort)(gateway + 1);
         const api = options.apiPort ?? await (0, port_finder_1.getFreePort)(css + 1);
-        // The ingress listener is an internal detail of this runtime, so it takes an
-        // OS-assigned port instead of claiming the neighbour of a planned service port.
-        const ingress = options.ingressPort ?? await (0, port_finder_1.getEphemeralLoopbackPort)();
+        // Tunnels (and the P2P data plane) terminate here, and this listener never treats a
+        // caller as local whatever headers it carries - that is the gate. Its port is the one
+        // number the user copies into a provider console, so it is predictable rather than
+        // random, and it is what the runtime reports as the tunnel origin.
+        const ingress = options.ingressPort ?? await (0, port_finder_1.findGatewayIngressPort)(gateway);
         return { gateway, css, api, ingress };
     }
     createListenEndpoint(options) {

package/dist/runtime/index.d.ts

@@ -10,7 +10,13 @@ export { createOpenAuthContext, registerManagedRuntimeServices, startApiRuntime,
 export type { RuntimeServices } from './lifecycle';
 export { GatewayProxy } from './Proxy';
 export { createGatewayAdminProxyAuthSecret } from './GatewayAdminProxyAuth';
-export { getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, readPortFile, requireFreePortForWildcard, resolveStableLoopbackPort } from './port-finder';
+export { findGatewayIngressPort, getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, isFreePortForWildcard, requireFreePortForWildcard } from './port-finder';
+export { assertUsableIngressPort, parseExplicitIngressPort, resolveIngressPort, IngressPortConflictError } from './ingress-port';
+export type { IngressPortDeclaration, IngressPortResolution, IngressPortSource } from './ingress-port';
+export { identifyIngressPortOccupants } from './ingress-occupant';
+export { getUnreservedEphemeralPort, listenOnUnreservedPort, PORT_RESERVATION_DIR_ENV, RESERVED_PORTS_ENV, portReservation, portReservationDir, readPortReservations, releasePort, reservePort, reservedPorts, } from './port-reservations';
+export type { PortReservation } from './port-reservations';
+export type { IngressPortOccupant, IngressPortOccupants } from './ingress-occupant';
 export { ensureTrailingSlash, INVALID_CONFIGURATION_PREFIX, validateBaseUrl } from './base-url';
 export type { ValidateBaseUrlOptions } from './base-url';
 export { applyEnv, loadEnvFile } from './env-utils';

package/dist/runtime/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.resolveStableLoopbackPort = exports.requireFreePortForWildcard = exports.readPortFile = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.reservedPorts = exports.reservePort = exports.releasePort = exports.readPortReservations = exports.portReservationDir = exports.portReservation = exports.RESERVED_PORTS_ENV = exports.PORT_RESERVATION_DIR_ENV = exports.listenOnUnreservedPort = exports.getUnreservedEphemeralPort = exports.identifyIngressPortOccupants = exports.IngressPortConflictError = exports.resolveIngressPort = exports.parseExplicitIngressPort = exports.assertUsableIngressPort = exports.requireFreePortForWildcard = exports.isFreePortForWildcard = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.findGatewayIngressPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = void 0;
 require("./configure-drizzle-solid");
 var package_root_1 = require("./package-root");
 Object.defineProperty(exports, "PACKAGE_ROOT", { enumerable: true, get: function () { return package_root_1.PACKAGE_ROOT; } });
@@ -30,12 +31,30 @@ Object.defineProperty(exports, "GatewayProxy", { enumerable: true, get: function
 var GatewayAdminProxyAuth_1 = require("./GatewayAdminProxyAuth");
 Object.defineProperty(exports, "createGatewayAdminProxyAuthSecret", { enumerable: true, get: function () { return GatewayAdminProxyAuth_1.createGatewayAdminProxyAuthSecret; } });
 var port_finder_1 = require("./port-finder");
+Object.defineProperty(exports, "findGatewayIngressPort", { enumerable: true, get: function () { return port_finder_1.findGatewayIngressPort; } });
 Object.defineProperty(exports, "getEphemeralLoopbackPort", { enumerable: true, get: function () { return port_finder_1.getEphemeralLoopbackPort; } });
 Object.defineProperty(exports, "getFreePort", { enumerable: true, get: function () { return port_finder_1.getFreePort; } });
 Object.defineProperty(exports, "getFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.getFreePortForWildcard; } });
-Object.defineProperty(exports, "readPortFile", { enumerable: true, get: function () { return port_finder_1.readPortFile; } });
+Object.defineProperty(exports, "isFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.isFreePortForWildcard; } });
 Object.defineProperty(exports, "requireFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.requireFreePortForWildcard; } });
-Object.defineProperty(exports, "resolveStableLoopbackPort", { enumerable: true, get: function () { return port_finder_1.resolveStableLoopbackPort; } });
+var ingress_port_1 = require("./ingress-port");
+Object.defineProperty(exports, "assertUsableIngressPort", { enumerable: true, get: function () { return ingress_port_1.assertUsableIngressPort; } });
+Object.defineProperty(exports, "parseExplicitIngressPort", { enumerable: true, get: function () { return ingress_port_1.parseExplicitIngressPort; } });
+Object.defineProperty(exports, "resolveIngressPort", { enumerable: true, get: function () { return ingress_port_1.resolveIngressPort; } });
+Object.defineProperty(exports, "IngressPortConflictError", { enumerable: true, get: function () { return ingress_port_1.IngressPortConflictError; } });
+var ingress_occupant_1 = require("./ingress-occupant");
+Object.defineProperty(exports, "identifyIngressPortOccupants", { enumerable: true, get: function () { return ingress_occupant_1.identifyIngressPortOccupants; } });
+var port_reservations_1 = require("./port-reservations");
+Object.defineProperty(exports, "getUnreservedEphemeralPort", { enumerable: true, get: function () { return port_reservations_1.getUnreservedEphemeralPort; } });
+Object.defineProperty(exports, "listenOnUnreservedPort", { enumerable: true, get: function () { return port_reservations_1.listenOnUnreservedPort; } });
+Object.defineProperty(exports, "PORT_RESERVATION_DIR_ENV", { enumerable: true, get: function () { return port_reservations_1.PORT_RESERVATION_DIR_ENV; } });
+Object.defineProperty(exports, "RESERVED_PORTS_ENV", { enumerable: true, get: function () { return port_reservations_1.RESERVED_PORTS_ENV; } });
+Object.defineProperty(exports, "portReservation", { enumerable: true, get: function () { return port_reservations_1.portReservation; } });
+Object.defineProperty(exports, "portReservationDir", { enumerable: true, get: function () { return port_reservations_1.portReservationDir; } });
+Object.defineProperty(exports, "readPortReservations", { enumerable: true, get: function () { return port_reservations_1.readPortReservations; } });
+Object.defineProperty(exports, "releasePort", { enumerable: true, get: function () { return port_reservations_1.releasePort; } });
+Object.defineProperty(exports, "reservePort", { enumerable: true, get: function () { return port_reservations_1.reservePort; } });
+Object.defineProperty(exports, "reservedPorts", { enumerable: true, get: function () { return port_reservations_1.reservedPorts; } });
 var base_url_1 = require("./base-url");
 Object.defineProperty(exports, "ensureTrailingSlash", { enumerable: true, get: function () { return base_url_1.ensureTrailingSlash; } });
 Object.defineProperty(exports, "INVALID_CONFIGURATION_PREFIX", { enumerable: true, get: function () { return base_url_1.INVALID_CONFIGURATION_PREFIX; } });

package/dist/runtime/ingress-occupant.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Who holds a port.
+ *
+ * A tunnel console forwards to a number, not to a process: if something else already listens
+ * there, binding "somewhere else" would make the tunnel reach that other process, and killing
+ * it is not this runtime's decision to make. So the only thing this module does is *name* the
+ * occupant (pid, command line, cwd, start time) so a refused start points at a culprit instead
+ * of at a number. Nothing here ever signals a process.
+ */
+export interface IngressPortOccupant {
+    pid: number;
+    /** Full command line when it could be read. */
+    command: string;
+    cwd?: string;
+    startedAt?: string;
+}
+export interface IngressPortOccupants {
+    port: number;
+    occupants: IngressPortOccupant[];
+    /**
+     * One line naming every occupant, for an error message. When nothing can be identified it
+     * says so explicitly: "taken by something we cannot name" is a different fact from "free".
+     */
+    description: string;
+}
+export interface IdentifyOccupantsDeps {
+    /** Runs a command and returns stdout. Injected in tests. */
+    exec?: (file: string, args: readonly string[]) => string;
+}
+/**
+ * Names every process listening on the port.
+ *
+ * `lsof` is the portable answer on macOS and most Linux images; `ss` covers Linux hosts
+ * without lsof. When neither is available the answer is "an unidentified listener", never a
+ * silent success.
+ */
+export declare function identifyIngressPortOccupants(port: number, deps?: IdentifyOccupantsDeps): IngressPortOccupants;
+/** One line for an operator: pid, command, cwd and start time of everything on the port. */
+export declare function describeOccupants(port: number, occupants: readonly IngressPortOccupant[], probeFailure?: string): string;

package/dist/runtime/ingress-occupant.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyIngressPortOccupants = identifyIngressPortOccupants;
+exports.describeOccupants = describeOccupants;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Names every process listening on the port.
+ *
+ * `lsof` is the portable answer on macOS and most Linux images; `ss` covers Linux hosts
+ * without lsof. When neither is available the answer is "an unidentified listener", never a
+ * silent success.
+ */
+function identifyIngressPortOccupants(port, deps = {}) {
+    const exec = deps.exec ?? defaultExec;
+    const pids = new Set();
+    let probeFailure;
+    try {
+        for (const pid of parseLsofPids(exec('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fp']))) {
+            pids.add(pid);
+        }
+    }
+    catch (error) {
+        probeFailure = `lsof: ${error.message}`;
+    }
+    if (pids.size === 0) {
+        try {
+            for (const pid of parseSsPids(exec('ss', ['-ltnpH', `sport = :${port}`]))) {
+                pids.add(pid);
+            }
+        }
+        catch (error) {
+            probeFailure = probeFailure
+                ? `${probeFailure}; ss: ${error.message}`
+                : `ss: ${error.message}`;
+        }
+    }
+    const occupants = [...pids].map((pid) => describeProcess(pid, exec));
+    return {
+        port,
+        occupants,
+        description: describeOccupants(port, occupants, probeFailure),
+    };
+}
+/** One line for an operator: pid, command, cwd and start time of everything on the port. */
+function describeOccupants(port, occupants, probeFailure) {
+    if (occupants.length === 0) {
+        return probeFailure
+            ? `port ${port} is not bindable and no process could be named (${probeFailure})`
+            : `port ${port} is not bindable and no listener reports it (a transient bind conflict)`;
+    }
+    return occupants.map((occupant) => {
+        const parts = [
+            `pid ${occupant.pid}`,
+            occupant.command || 'command unknown',
+            occupant.cwd ? `cwd ${occupant.cwd}` : undefined,
+            occupant.startedAt ? `started ${occupant.startedAt}` : undefined,
+        ].filter(Boolean);
+        return parts.join(' · ');
+    }).join('; ');
+}
+function defaultExec(file, args) {
+    return (0, node_child_process_1.execFileSync)(file, [...args], { encoding: 'utf8', timeout: 15_000 });
+}
+function parseLsofPids(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('p'))
+        .map((line) => Number.parseInt(line.slice(1), 10))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+function parseSsPids(output) {
+    const pids = new Set();
+    for (const match of output.matchAll(/pid=(\d+)/gu)) {
+        const pid = Number.parseInt(match[1], 10);
+        if (Number.isInteger(pid) && pid > 0) {
+            pids.add(pid);
+        }
+    }
+    return [...pids];
+}
+function describeProcess(pid, exec) {
+    let command = '';
+    let startedAt;
+    try {
+        const line = exec('ps', ['-o', 'lstart=,command=', '-p', String(pid)]).trim();
+        // `lstart` is a fixed 24-character timestamp ("Mon Sep 22 17:28:46 2026"), so the command
+        // starts right after it; anything shorter is a bare command line.
+        const stamp = /^[A-Z][a-z]{2} [A-Z][a-z]{2} {1,2}\d{1,2} \d{2}:\d{2}:\d{2} \d{4}\s+/u.exec(line);
+        if (stamp) {
+            startedAt = stamp[0].trim();
+            command = line.slice(stamp[0].length).trim();
+        }
+        else {
+            command = line;
+        }
+    }
+    catch {
+        // The process may have exited between the port probe and this call.
+    }
+    let cwd;
+    try {
+        const line = exec('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']).trim();
+        cwd = line.split('\n').find((entry) => entry.startsWith('n'))?.slice(1).trim() || undefined;
+    }
+    catch {
+        // cwd is optional evidence.
+    }
+    return { pid, command, ...(cwd ? { cwd } : {}), ...(startedAt ? { startedAt } : {}) };
+}
+//# sourceMappingURL=ingress-occupant.js.map

package/dist/runtime/ingress-port.d.ts

@@ -0,0 +1,89 @@
+import { type DeclaredOriginReadResult } from '../tunnel/TunnelDeclaredOrigin';
+/**
+ * Where the tunnel entry (the listener every remote forwarder terminates on) is bound.
+ *
+ * Order, strictest first:
+ *   1. an explicit `XPOD_GATEWAY_INGRESS_PORT` — an operator or harness pin is never overridden
+ *      and never silently moved to another port;
+ *   2. the port the *active* profile's provider console already declares (SakuraFrp
+ *      `GET /v4/tunnels` `local_port`; the Cloudflare dashboard's remote configuration read
+ *      back through the connector) — adopted when it is free, so the operator does not have to
+ *      edit the console to match the runtime;
+ *   3. `findGatewayIngressPort(gatewayPort)` — the predictable, dynamic gateway+3..+9 entry.
+ *
+ * Both strict sources are strict about *being taken*: a port somebody else holds fails the
+ * start with the occupant named (pid, command line, cwd). Nothing here signals a process, and
+ * nothing silently falls back — a tunnel that forwards to a number must never find a different
+ * process listening on it.
+ */
+export type IngressPortSource = 'explicit' | 'console-declared' | 'gateway-default';
+export interface IngressProfileLike {
+    id: string;
+    provider: string;
+    credentialEnvKey?: string;
+    credentialConfigured?: boolean;
+}
+/** A port a provider console declares for this runtime's origin. */
+export interface IngressPortDeclaration {
+    profileId: string;
+    provider: string;
+    port: number;
+    readBack: string;
+    scheme?: string;
+}
+export interface IngressPortResolution {
+    port: number;
+    source: IngressPortSource;
+    /** The active profile's declaration that was adopted, when there was one. */
+    declared?: IngressPortDeclaration;
+    /**
+     * Declarations from profiles that are *not* active.
+     *
+     * They are reported because two profiles naming different ports is exactly the confusion
+     * this resolution exists to end; only the active one may decide the listener.
+     */
+    inactiveDeclarations: IngressPortDeclaration[];
+}
+export interface IngressPortLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+export interface IngressPortDeps {
+    findDefaultPort(mainPort: number): Promise<number>;
+    isFree(port: number): Promise<boolean>;
+    identifyOccupants(port: number): string;
+    readDeclaredOrigin(profile: IngressProfileLike, options: {
+        env: Record<string, string | undefined>;
+        active: boolean;
+    }): Promise<DeclaredOriginReadResult>;
+    logger: IngressPortLogger;
+}
+export interface IngressPortRequest {
+    mainPort: number;
+    env?: Record<string, string | undefined>;
+    profiles?: readonly IngressProfileLike[];
+    activeProfileId?: string;
+    /** Service ports this run serves (gateway/CSS/API): never a valid tunnel origin. */
+    reservedPorts?: Iterable<number>;
+    deps?: Partial<IngressPortDeps>;
+}
+/** A strict port that could not be taken: the occupant is named, and nothing was signalled. */
+export declare class IngressPortConflictError extends Error {
+    readonly port: number;
+    readonly occupant: string;
+    constructor(port: number, occupant: string);
+}
+export declare function defaultIngressPortDeps(): IngressPortDeps;
+/**
+ * Validates a port that came from outside this runtime (an operator pin or a console).
+ *
+ * Zero, out-of-range and privileged ports are refused with the reason spelled out: binding
+ * them either fails later with a bare errno, or needs privileges the runtime should not hold.
+ */
+export declare function assertUsableIngressPort(port: number, options: {
+    label: string;
+    reservedPorts?: ReadonlySet<number>;
+}): void;
+/** Reads the explicit pin strictly: present but malformed is an error, not an absent value. */
+export declare function parseExplicitIngressPort(raw: string | undefined): number | undefined;
+export declare function resolveIngressPort(request: IngressPortRequest): Promise<IngressPortResolution>;