@undefineds.co/xpod 0.4.13 → 0.4.14

package/dist/runtime/Proxy.d.ts

@@ -21,7 +21,22 @@ export declare class GatewayProxy {
     private readonly nativeUpgradeRelay?;
     /** Sockets created by `upgrade` events, dropped on shutdown. */
     private readonly upgradeSockets;
+    /**
+     * Loopback-only listener used as the origin of everything that forwards remote
+     * traffic to this Gateway (managed tunnels, P2P data plane). Requests accepted
+     * there are never treated as local, so a forwarded request cannot inherit the
+     * trust that a real local client has.
+     */
+    private readonly ingressPort?;
+    private ingressServer?;
     constructor(port: number | undefined, supervisor: Supervisor, bindHost?: string, options?: GatewayProxyOptions);
+    /**
+     * Builds one HTTP listener plus its WebSocket routing.
+     *
+     * `untrustedIngress` marks the listener that tunnels and the P2P data plane
+     * connect to; see `ingressPort`.
+     */
+    private createListener;
     /**
      * Upgraded sockets outlive the HTTP request that created them; they are
      * tracked so shutdown can drop them instead of waiting for a long lived
@@ -52,6 +67,7 @@ export declare class GatewayProxy {
      * (oven-sh/bun#28396), so waiting forever would block gateway restarts.
      */
     private closeServer;
+    private ingressListenEndpoint;
     private handleRequest;
     private isApiWebProductPath;
     private shouldRouteToApi;
@@ -102,4 +118,10 @@ export interface GatewayProxyOptions {
      * client socket at all.
      */
     nativeUpgradeRelay?: boolean;
+    /**
+     * Port for the loopback-only ingress listener that remote forwarding paths
+     * (managed tunnels, P2P data plane) use as their origin. Omit it when the
+     * Gateway has no remote ingress.
+     */
+    ingressPort?: number;
 }

package/dist/runtime/Proxy.js

@@ -58,6 +58,7 @@ class GatewayProxy {
         this.baseUrl = options.baseUrl;
         this.internalAdminAuthSecret = options.internalAdminAuthSecret;
         this.clientRemoteAddressResolver = options.clientRemoteAddressResolver;
+        this.ingressPort = options.ingressPort;
         this.proxy = http_proxy_1.default.createProxyServer({
             xfwd: true,
         });
@@ -87,14 +88,26 @@ class GatewayProxy {
                 outgoing.end(rewritten.body);
             });
         });
-        this.server = http_1.default.createServer(this.handleRequest.bind(this));
+        this.server = this.createListener(false);
+        if (this.ingressPort !== undefined) {
+            this.ingressServer = this.createListener(true);
+        }
         if (options.nativeUpgradeRelay ?? isBunRuntime()) {
             this.nativeUpgradeRelay = new BunNativeUpgradeRelay_1.BunNativeUpgradeRelay({
                 logger: this.logger,
                 fallback: (req, socket, head, target) => this.relayUpgradeWithHttpProxy(req, socket, head, target),
             });
         }
-        this.server.on('upgrade', (req, socket, head) => {
+    }
+    /**
+     * Builds one HTTP listener plus its WebSocket routing.
+     *
+     * `untrustedIngress` marks the listener that tunnels and the P2P data plane
+     * connect to; see `ingressPort`.
+     */
+    createListener(untrustedIngress) {
+        const server = http_1.default.createServer((req, res) => this.handleRequest(req, res, untrustedIngress));
+        server.on('upgrade', (req, socket, head) => {
             this.trackUpgradeSocket(socket);
             const target = this.resolveUpgradeTarget(req.url ?? '/');
             if (!target) {
@@ -107,6 +120,7 @@ class GatewayProxy {
             }
             this.relayUpgradeWithHttpProxy(req, socket, head, target);
         });
+        return server;
     }
     /**
      * Upgraded sockets outlive the HTTP request that created them; they are
@@ -143,6 +157,10 @@ class GatewayProxy {
     async start() {
         await this.runtimeHost.listen(this.server, this.listenEndpoint);
         this.logger.info(`Listening on ${this.runtimeHost.formatListenEndpoint(this.listenEndpoint)}`);
+        if (this.ingressServer) {
+            await this.runtimeHost.listen(this.ingressServer, this.ingressListenEndpoint());
+            this.logger.info(`Ingress listener on 127.0.0.1:${this.ingressPort} (never local)`);
+        }
     }
     async stop() {
         this.nativeUpgradeRelay?.close();
@@ -153,7 +171,10 @@ class GatewayProxy {
         }
         this.upgradeSockets.clear();
         this.proxy.close();
-        await this.closeServer();
+        await this.closeServer(this.server, this.listenEndpoint);
+        if (this.ingressServer) {
+            await this.closeServer(this.ingressServer, this.ingressListenEndpoint());
+        }
     }
     /**
      * Closes the listener with a bounded wait.
@@ -164,8 +185,8 @@ class GatewayProxy {
      * back once a WebSocket was closed from the server side
      * (oven-sh/bun#28396), so waiting forever would block gateway restarts.
      */
-    async closeServer() {
-        const closing = this.runtimeHost.close(this.server, this.listenEndpoint);
+    async closeServer(server, endpoint) {
+        const closing = this.runtimeHost.close(server, endpoint);
         let timer;
         const timedOut = await Promise.race([
             closing.then(() => false),
@@ -182,7 +203,10 @@ class GatewayProxy {
             void closing.catch(() => undefined);
         }
     }
-    handleRequest(req, res) {
+    ingressListenEndpoint() {
+        return this.runtimeHost.createListenEndpoint({ port: this.ingressPort, host: '127.0.0.1' });
+    }
+    handleRequest(req, res, untrustedIngress = false) {
         const url = req.url ?? '/';
         // Route matching must ignore the query string: OIDC callbacks and other
         // product URLs arrive as `/ai-connections?code=...`, and exact-path
@@ -190,7 +214,10 @@ class GatewayProxy {
         const pathname = url.split('?')[0];
         const origin = req.headers.origin;
         const originalRemoteAddress = this.clientRemoteAddressResolver?.(req) ?? req.socket.remoteAddress;
-        const originalClientLoopback = (0, GatewayAdminProxyAuth_1.isLoopbackRemoteAddress)(originalRemoteAddress);
+        // 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);
         (0, GatewayAdminProxyAuth_1.stripGatewayAdminProxyHeaders)(req.headers);
         if (internalPodProxyHeaders) {

package/dist/runtime/bootstrap.d.ts

@@ -28,6 +28,17 @@ export interface RuntimeBootstrapState {
 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>;
+/**
+ * Local endpoints the edge agent uses when it serves P2P peer traffic.
+ *
+ * `targetBaseUrl` is where forwarded peer requests are sent: the ingress listener,
+ * which the Gateway never treats as local. `lanBaseUrl` stays on the gateway
+ * listener because other devices on the LAN must be able to reach it.
+ */
+export declare function resolveP2PLocalBaseUrls(state: RuntimeBootstrapState): {
+    targetBaseUrl?: string;
+    lanBaseUrl?: string;
+};
 export declare function buildRuntimeShorthand(runtimeEnv: Record<string, string | undefined>, options: XpodRuntimeOptions, state: RuntimeBootstrapState, baseEnv?: Record<string, string | undefined>): Record<string, string | number | boolean>;
 export declare function createCssRuntimeConfig(state: RuntimeBootstrapState, _open?: boolean, platform?: Pick<RuntimePlatform, 'dirname' | 'ensureDir' | 'joinPath' | 'readTextFile' | 'writeTextFile'>): string;
 export declare function initRuntimeLogger(level: string, platform?: Pick<RuntimePlatform, 'cwd' | 'joinPath'>): void;

package/dist/runtime/bootstrap.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cssAuthModeConfigImports = cssAuthModeConfigImports;
 exports.resolveRuntimeBootstrap = resolveRuntimeBootstrap;
 exports.buildRuntimeEnv = buildRuntimeEnv;
+exports.resolveP2PLocalBaseUrls = resolveP2PLocalBaseUrls;
 exports.buildRuntimeShorthand = buildRuntimeShorthand;
 exports.createCssRuntimeConfig = createCssRuntimeConfig;
 exports.initRuntimeLogger = initRuntimeLogger;
@@ -204,6 +205,7 @@ function buildRuntimeEnv(state, options, envFromFile = {}) {
         API_HOST: state.bindHost,
         API_SOCKET_PATH: state.sockets.api,
         XPOD_MAIN_PORT: state.ports.gateway !== undefined ? String(state.ports.gateway) : undefined,
+        XPOD_GATEWAY_INGRESS_PORT: state.ports.ingress !== undefined ? String(state.ports.ingress) : undefined,
         XPOD_GATEWAY_ADMIN_PROXY_AUTH_SECRET: state.gatewayAdminProxyAuthSecret,
         // Auto-provision may write these during API startup. Include them even when
         // undefined so RuntimeEnvironmentSession can restore/clear them afterwards.
@@ -222,11 +224,28 @@ function buildRuntimeEnv(state, options, envFromFile = {}) {
     };
     return (0, AuthMode_1.applyAuthModeEnv)(runtimeEnv, state.cssAuthMode);
 }
+/**
+ * Local endpoints the edge agent uses when it serves P2P peer traffic.
+ *
+ * `targetBaseUrl` is where forwarded peer requests are sent: the ingress listener,
+ * which the Gateway never treats as local. `lanBaseUrl` stays on the gateway
+ * listener because other devices on the LAN must be able to reach it.
+ */
+function resolveP2PLocalBaseUrls(state) {
+    if (state.transport !== 'port' || state.ports.gateway === undefined) {
+        return {};
+    }
+    return {
+        targetBaseUrl: state.ports.ingress === undefined ? undefined : `http://127.0.0.1:${state.ports.ingress}/`,
+        lanBaseUrl: `http://127.0.0.1:${state.ports.gateway}/`,
+    };
+}
 function buildRuntimeShorthand(runtimeEnv, options, state, baseEnv = NodeRuntimePlatform_1.nodeRuntimePlatform.baseEnv) {
     const envValue = (key) => runtimeEnv[key] ?? baseEnv[key];
     const externalOidcIssuer = (0, oidc_issuer_1.resolveExternalOidcIssuer)({
         SOLID_OIDC_ISSUER: envValue('SOLID_OIDC_ISSUER'),
     });
+    const p2pLocalBaseUrls = resolveP2PLocalBaseUrls(state);
     return {
         ...withDefinedEntries([
             ['baseStorageDomain', envValue('CSS_BASE_STORAGE_DOMAIN')],
@@ -249,7 +268,8 @@ function buildRuntimeShorthand(runtimeEnv, options, state, baseEnv = NodeRuntime
             ['nodeId', envValue('XPOD_NODE_ID')],
             ['nodeToken', envValue('XPOD_NODE_TOKEN')],
             ['p2pEnabled', envValue('XPOD_P2P_ENABLED')],
-            ['p2pTargetBaseUrl', envValue('XPOD_P2P_TARGET_BASE_URL')],
+            ['p2pTargetBaseUrl', envValue('XPOD_P2P_TARGET_BASE_URL') ?? p2pLocalBaseUrls.targetBaseUrl],
+            ['p2pLanBaseUrl', envValue('XPOD_P2P_LAN_BASE_URL') ?? p2pLocalBaseUrls.lanBaseUrl],
             ['p2pLabel', envValue('XPOD_P2P_LABEL')],
             ['p2pAcceptIntervalMs', envValue('XPOD_P2P_ACCEPT_INTERVAL_MS')],
             ['p2pConnectTimeoutMs', envValue('XPOD_P2P_CONNECT_TIMEOUT_MS')],

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

@@ -30,6 +30,7 @@ export declare function buildApiChildEnv(options: {
     apiPort: number;
     mainPort: number;
     cssPort: number;
+    ingressPort?: number;
     baseUrl: string;
     rdfIndexPath?: string;
     authMode?: AuthMode | string;

package/dist/runtime/css-process.js

@@ -271,6 +271,7 @@ function buildApiChildEnv(options) {
         ...(options.externalOidcIssuer ? { oidcIssuer: options.externalOidcIssuer } : {}),
         API_PORT: options.apiPort.toString(),
         XPOD_MAIN_PORT: options.mainPort.toString(),
+        ...(options.ingressPort !== undefined ? { XPOD_GATEWAY_INGRESS_PORT: options.ingressPort.toString() } : {}),
         CSS_PORT: options.cssPort.toString(),
         CSS_BASE_URL: baseUrl,
         ...(options.gatewayAdminProxyAuthSecret ? { XPOD_GATEWAY_ADMIN_PROXY_AUTH_SECRET: options.gatewayAdminProxyAuthSecret } : {}),

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

@@ -23,7 +23,10 @@ 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);
-        return { gateway, css, api };
+        // 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)();
+        return { gateway, css, api, ingress };
     }
     createListenEndpoint(options) {
         if (options.socketPath) {

package/dist/runtime/host/types.d.ts

@@ -24,12 +24,18 @@ export interface RuntimePortAllocationOptions {
     gatewayPort?: number;
     cssPort?: number;
     apiPort?: number;
+    ingressPort?: number;
     basePort?: number;
 }
 export interface RuntimePorts {
     gateway: number;
     css: number;
     api: number;
+    /**
+     * Loopback-only listener that remote forwarding paths (managed tunnels, P2P
+     * data plane) use as their origin, so their requests never count as local.
+     */
+    ingress: number;
 }
 export interface RuntimeHost {
     readonly name: string;

package/dist/runtime/index.d.ts

@@ -10,7 +10,7 @@ export { createOpenAuthContext, registerManagedRuntimeServices, startApiRuntime,
 export type { RuntimeServices } from './lifecycle';
 export { GatewayProxy } from './Proxy';
 export { createGatewayAdminProxyAuthSecret } from './GatewayAdminProxyAuth';
-export { getFreePort, getFreePortForWildcard } from './port-finder';
+export { getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, readPortFile, requireFreePortForWildcard, resolveStableLoopbackPort } from './port-finder';
 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,6 @@
 "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.getFreePortForWildcard = exports.getFreePort = 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 = 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;
 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,8 +30,12 @@ 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, "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, "requireFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.requireFreePortForWildcard; } });
+Object.defineProperty(exports, "resolveStableLoopbackPort", { enumerable: true, get: function () { return port_finder_1.resolveStableLoopbackPort; } });
 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/lifecycle.js

@@ -108,6 +108,7 @@ async function startGatewayRuntime({ state, host, supervisor, shutdownHandler, g
         supervisor,
         internalAdminAuthSecret: state.gatewayAdminProxyAuthSecret,
         clientRemoteAddressResolver,
+        ingressPort: state.ports.ingress,
         targets: {
             css: state.transport === 'socket' ? { socketPath: state.sockets.css } : { url: `http://127.0.0.1:${state.ports.css}` },
             api: state.transport === 'socket' ? { socketPath: state.sockets.api } : { url: `http://127.0.0.1:${state.ports.api}` },

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

@@ -1,7 +1,37 @@
 export declare function getFreePort(basePort: number, host?: string, timeoutMs?: number): Promise<number>;
+/**
+ * Loopback port handed out by the OS for a listener that must not collide with ports the
+ * embedding process plans for other services.
+ *
+ * Probing next to the ports this runtime already owns is not safe: a host that allocates
+ * `gateway + 10`/`gateway + 11` (the full integration matrix does) has already reserved
+ * the neighbour of our own `api` port for another runtime, and binding it steals that
+ * runtime's service.
+ */
+export declare function getEphemeralLoopbackPort(): Promise<number>;
+/**
+ * The ingress port this deployment should keep using.
+ *
+ * Remote tunnels forward to a port the operator typed into a provider console, so an
+ * OS-assigned port would invalidate that copy on every restart. The port is remembered in
+ * the runtime state directory; if something else took it meanwhile, a new one is chosen and
+ * persisted — the caller reports the change so the stale console value can be corrected.
+ */
+export declare function resolveStableLoopbackPort(stateFile: string): Promise<{
+    port: number;
+    changed: boolean;
+}>;
+export declare function readPortFile(stateFile: string): number | undefined;
 /**
  * Allocates a port for child services that bind wildcard addresses.
  * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
  * can miss an occupied port on the other address family.
  */
+/**
+ * Takes exactly this port or fails.
+ *
+ * A port that a tunnel console forwards to cannot be substituted: `getFreePortForWildcard`
+ * scans upward, which would leave the runtime listening somewhere the tunnel never reaches.
+ */
+export declare function requireFreePortForWildcard(port: number, timeoutMs?: number): Promise<number>;
 export declare function getFreePortForWildcard(basePort: number, timeoutMs?: number): Promise<number>;

package/dist/runtime/port-finder.js

@@ -4,9 +4,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFreePort = getFreePort;
+exports.getEphemeralLoopbackPort = getEphemeralLoopbackPort;
+exports.resolveStableLoopbackPort = resolveStableLoopbackPort;
+exports.readPortFile = readPortFile;
+exports.requireFreePortForWildcard = requireFreePortForWildcard;
 exports.getFreePortForWildcard = getFreePortForWildcard;
 const node_net_1 = __importDefault(require("node:net"));
 const node_os_1 = __importDefault(require("node:os"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const HIGHEST_PORT = 65_535;
 const PORT_PROBE_TIMEOUT_MS = 1_000;
 const RETRYABLE_PORT_ERRORS = new Set([
@@ -105,6 +111,65 @@ async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_
     }
     throw new Error(`No open port available from ${host}:${basePort} to ${host}:${HIGHEST_PORT}`);
 }
+/**
+ * Loopback port handed out by the OS for a listener that must not collide with ports the
+ * embedding process plans for other services.
+ *
+ * Probing next to the ports this runtime already owns is not safe: a host that allocates
+ * `gateway + 10`/`gateway + 11` (the full integration matrix does) has already reserved
+ * the neighbour of our own `api` port for another runtime, and binding it steals that
+ * runtime's service.
+ */
+async function getEphemeralLoopbackPort() {
+    return await new Promise((resolve, reject) => {
+        const server = node_net_1.default.createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(port);
+            });
+        });
+    });
+}
+/**
+ * The ingress port this deployment should keep using.
+ *
+ * Remote tunnels forward to a port the operator typed into a provider console, so an
+ * OS-assigned port would invalidate that copy on every restart. The port is remembered in
+ * the runtime state directory; if something else took it meanwhile, a new one is chosen and
+ * persisted — the caller reports the change so the stale console value can be corrected.
+ */
+async function resolveStableLoopbackPort(stateFile) {
+    const remembered = readPortFile(stateFile);
+    if (remembered !== undefined && await canListen(remembered, '127.0.0.1')) {
+        return { port: remembered, changed: false };
+    }
+    const port = await getEphemeralLoopbackPort();
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
+        (0, node_fs_1.writeFileSync)(stateFile, `${port}\n`);
+    }
+    catch {
+        // A deployment without a writable state directory still gets a working port; it just
+        // cannot promise the same one next time.
+    }
+    return { port, changed: remembered !== undefined };
+}
+function readPortFile(stateFile) {
+    try {
+        const port = Number.parseInt((0, node_fs_1.readFileSync)(stateFile, 'utf8').trim(), 10);
+        return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function hasIpv6Address() {
     return Object.values(node_os_1.default.networkInterfaces()).some((entries) => entries?.some((entry) => entry.family === 'IPv6'));
 }
@@ -113,6 +178,24 @@ function hasIpv6Address() {
  * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
  * can miss an occupied port on the other address family.
  */
+/**
+ * Takes exactly this port or fails.
+ *
+ * A port that a tunnel console forwards to cannot be substituted: `getFreePortForWildcard`
+ * scans upward, which would leave the runtime listening somewhere the tunnel never reaches.
+ */
+async function requireFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`ingress port ${port} is not a valid port number`);
+    }
+    if (!await canListen(port, '0.0.0.0', timeoutMs)) {
+        throw new Error(`ingress port ${port} is already in use; free it or point the tunnel at another port`);
+    }
+    if (hasIpv6Address() && !await canListen(port, '::', timeoutMs)) {
+        throw new Error(`ingress port ${port} is already in use on IPv6; free it or point the tunnel at another port`);
+    }
+    return port;
+}
 async function getFreePortForWildcard(basePort, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
     const probeIpv6 = hasIpv6Address();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {

package/dist/runtime/runner/node/NodeGatewayRuntimeRunner.js

@@ -15,6 +15,7 @@ class NodeGatewayRuntimeRunner {
             runtimeHost: options.runtimeHost,
             internalAdminAuthSecret: options.internalAdminAuthSecret,
             clientRemoteAddressResolver: options.clientRemoteAddressResolver,
+            ingressPort: options.ingressPort,
         });
         gateway.setTargets(options.targets);
         await gateway.start();

package/dist/runtime/runner/types.d.ts

@@ -33,6 +33,11 @@ export interface GatewayRuntimeRunnerStartOptions {
     supervisor: Supervisor;
     internalAdminAuthSecret: string;
     clientRemoteAddressResolver?: (req: http.IncomingMessage) => string | undefined;
+    /**
+     * Loopback-only ingress listener for remote forwarding paths (tunnels, P2P).
+     * Port transport only; socket transport has no remote ingress.
+     */
+    ingressPort?: number;
     targets: {
         css: RuntimeConnectionTarget;
         api: RuntimeConnectionTarget;

package/dist/runtime/runtime-types.d.ts

@@ -10,6 +10,7 @@ export interface XpodRuntimePorts {
     gateway?: number;
     css?: number;
     api?: number;
+    ingress?: number;
 }
 export interface XpodRuntimeSockets {
     gateway?: string;

package/dist/test-utils/local-managed-client-p2p-e2e-smoke.js

@@ -38,7 +38,7 @@ async function runLocalManagedClientP2PE2ESmoke(options = {}) {
         const { token: serviceToken } = await serviceTokenRepo.createToken({
             serviceType: 'cloud',
             serviceId: 'managed-client-smoke',
-            scopes: ['reachability:read', 'reachability:write'],
+            scopes: ['network:read', 'network:write'],
         });
         const signalApi = await startSignalApi({
             nodeRepo,

package/dist/tunnel/LocalTunnelProvider.d.ts

@@ -10,6 +10,8 @@ export interface LocalTunnelProviderOptions {
     publicUrl?: string;
     /** cloudflared 可执行文件路径 (默认 'cloudflared') */
     cloudflaredPath?: string;
+    /** 等待代理发布的毫秒数；超时后状态为 failed，而不是"仍在连接" */
+    connectTimeoutMs?: number;
 }
 /**
  * Local Tunnel Provider
@@ -28,6 +30,7 @@ export declare class LocalTunnelProvider implements TunnelProvider {
     private readonly tunnelToken;
     private readonly publicUrl?;
     private readonly cloudflaredPath;
+    private readonly connectTimeoutMs;
     private process;
     private status;
     private currentConfig;
@@ -46,6 +49,8 @@ export declare class LocalTunnelProvider implements TunnelProvider {
     /**
      * 解析并打印 cloudflared 日志
      */
+    /** Set when the dashboard's origin port and this runtime's ingress port disagree. */
+    private originMismatch?;
     private logOutput;
     /**
      * 停止隧道
@@ -86,3 +91,13 @@ export declare class LocalTunnelProvider implements TunnelProvider {
      */
     isManagedByUs(): boolean;
 }
+/**
+ * The origin a remotely-managed tunnel declares for its hostname.
+ *
+ * Both halves are reported: pointing the dashboard at `https://localhost:<port>` while this
+ * runtime serves plain HTTP there fails the TLS handshake, and the edge shows only a 502.
+ */
+export declare function readDashboardOrigin(output: string): {
+    scheme: string;
+    port: number;
+} | undefined;