@undefineds.co/xpod 0.4.13 → 0.4.14

package/dist/api/handlers/ReachabilityHandler.js

@@ -42,7 +42,7 @@ function registerReachabilityRoutes(server, options) {
         }
     }, { optionalAuth: true });
     server.post('/v1/signal/nodes/:nodeId/sessions', async (request, response, params) => {
-        const access = resolveSessionAccess(request, params.nodeId);
+        const access = await resolveSessionAccess(request, params.nodeId, options, 'node');
         if (!access.allowed) {
             sendJson(response, access.status, { error: access.error });
             return;
@@ -119,7 +119,7 @@ function registerReachabilityRoutes(server, options) {
         sendJson(response, 400, { error: 'kind must be p2p or relay' });
     });
     server.get('/v1/signal/nodes/:nodeId/sessions', async (request, response, params) => {
-        const access = resolveSessionAccess(request, params.nodeId);
+        const access = await resolveSessionAccess(request, params.nodeId, options, 'node');
         if (!access.allowed) {
             sendJson(response, access.status, { error: access.error });
             return;
@@ -137,7 +137,7 @@ function registerReachabilityRoutes(server, options) {
         }
     });
     server.get('/v1/signal/nodes/:nodeId/sessions/:sessionId', async (request, response, params) => {
-        const access = resolveSessionAccess(request, params.nodeId);
+        const access = await resolveSessionAccess(request, params.nodeId, options, 'session');
         if (!access.allowed) {
             sendJson(response, access.status, { error: access.error });
             return;
@@ -155,7 +155,7 @@ function registerReachabilityRoutes(server, options) {
         }
     });
     server.post('/v1/signal/nodes/:nodeId/sessions/:sessionId/candidates', async (request, response, params) => {
-        const access = resolveSessionAccess(request, params.nodeId);
+        const access = await resolveSessionAccess(request, params.nodeId, options, 'session');
         if (!access.allowed) {
             sendJson(response, access.status, { error: access.error });
             return;
@@ -221,7 +221,7 @@ function resolveAccess(request, nodeId) {
     }
     return { allowed: true, audience: 'public' };
 }
-function resolveSessionAccess(request, nodeId) {
+async function resolveSessionAccess(request, nodeId, options, target) {
     const auth = request.auth;
     if (!auth) {
         return { allowed: false, status: 401, error: 'Authentication required' };
@@ -233,9 +233,26 @@ function resolveSessionAccess(request, nodeId) {
         return { allowed: true, kind: 'node', nodeId: auth.nodeId };
     }
     if ((0, AuthContext_1.isServiceAuth)(auth)) {
+        // Service principals act for the deployment, so they must carry the scope that
+        // covers reachability sessions instead of being trusted by principal type alone.
+        if (!(0, AuthContext_1.hasScope)(auth, 'network:write')) {
+            return { allowed: false, status: 403, error: 'Creating a reachability session requires network:write' };
+        }
         return { allowed: true, kind: 'service' };
     }
     if ((0, AuthContext_1.isSolidAuth)(auth)) {
+        // Node-wide operations need a resolvable relationship to the node (Pod ownership or
+        // an explicit grant): being logged in says nothing about this node. Operations on one
+        // session are gated by session ownership instead, so the owner keeps access to their
+        // own session even when node-wide discovery is not available to them.
+        if (target === 'node') {
+            const permitted = options.canAccessNode
+                ? await options.canAccessNode(nodeId, auth.webId)
+                : false;
+            if (!permitted) {
+                return { allowed: false, status: 403, error: 'WebID is not authorized for this node' };
+            }
+        }
         return { allowed: true, kind: 'solid', webId: auth.webId };
     }
     return { allowed: false, status: 403, error: 'Unsupported reachability session credentials' };

package/dist/api/network/NetworkEnvironmentConfigurationStore.d.ts

@@ -2,7 +2,12 @@ import type { NetworkConfigurationPatch, NetworkConfigurationStore, NetworkDesir
 type Env = Record<string, string | undefined>;
 export interface NetworkEnvironmentConfigurationStoreOptions {
     read(): Env | Promise<Env>;
-    write(patch: Record<string, string>): void | Promise<void>;
+    /**
+     * Persists a patch. `removals` lists keys that must be deleted from the environment
+     * instead of overwritten — deleting a profile has to take its credential with it,
+     * otherwise the leftover secret rebuilds the tunnel the user just closed.
+     */
+    write(patch: Record<string, string>, removals?: string[]): void | Promise<void>;
 }
 export declare class NetworkEnvironmentConfigurationStore implements NetworkConfigurationStore {
     private readonly options;

package/dist/api/network/NetworkEnvironmentConfigurationStore.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NetworkEnvironmentConfigurationStore = void 0;
+const TunnelProfiles_1 = require("../../tunnel/TunnelProfiles");
+const TunnelProviderCatalog_1 = require("../../tunnel/TunnelProviderCatalog");
 class NetworkEnvironmentConfigurationStore {
     constructor(options) {
         this.options = options;
@@ -10,9 +12,13 @@ class NetworkEnvironmentConfigurationStore {
     }
     async update(patch) {
         const current = await this.options.read();
-        const envPatch = environmentPatch(patch, current);
-        await this.options.write(envPatch);
-        return configurationFromEnv({ ...current, ...envPatch });
+        const { envPatch, removals } = environmentPatch(patch, current);
+        await this.options.write(envPatch, removals);
+        const next = { ...current, ...envPatch };
+        for (const key of removals) {
+            delete next[key];
+        }
+        return configurationFromEnv(next);
     }
 }
 exports.NetworkEnvironmentConfigurationStore = NetworkEnvironmentConfigurationStore;
@@ -35,7 +41,12 @@ function configurationFromEnv(env) {
             ...(env.XPOD_HTTPS_KEY_PATH ? { certificateKeyPath: env.XPOD_HTTPS_KEY_PATH } : {}),
             renewBeforeDays: positiveInteger(env.XPOD_ACME_RENEW_BEFORE_DAYS, 30),
         },
-        tunnelProfiles: { activeProfileId: env.XPOD_TUNNEL_ACTIVE_PROFILE_ID ?? '', profiles },
+        tunnelProfiles: {
+            activeProfileId: env.XPOD_TUNNEL_ACTIVE_PROFILE_ID !== undefined
+                ? (env.XPOD_TUNNEL_ACTIVE_PROFILE_ID.trim() || TunnelProfiles_1.TUNNEL_ACTIVE_PROFILE_NONE)
+                : '',
+            profiles,
+        },
         p2p: {
             enabled: env.XPOD_P2P_ENABLED === 'true',
             signalService: env.XPOD_P2P_SIGNAL_SERVICE ?? '',
@@ -45,6 +56,7 @@ function configurationFromEnv(env) {
 }
 function environmentPatch(patch, current) {
     const output = {};
+    const removals = new Set();
     if (patch.domainDns) {
         assign(output, 'XPOD_DNS_DOMAIN', patch.domainDns.domain);
         assign(output, 'XPOD_DDNS_ENABLED', boolString(patch.domainDns.ddnsEnabled));
@@ -57,8 +69,10 @@ function environmentPatch(patch, current) {
         assign(output, 'XPOD_HTTPS_MODE', patch.https.enabled === undefined ? undefined : patch.https.enabled ? 'acme' : 'off');
         assign(output, 'XPOD_ACME_EMAIL', patch.https.acmeEmail);
         assign(output, 'XPOD_ACME_DOMAINS', patch.https.domains?.join(','));
-        assign(output, 'XPOD_HTTPS_CERT_PATH', patch.https.certificatePath);
-        assign(output, 'XPOD_HTTPS_KEY_PATH', patch.https.certificateKeyPath);
+        // The runtime reads the ACME key names; the settings page used to write
+        // XPOD_HTTPS_* which nothing consumed.
+        assign(output, 'XPOD_ACME_CERTIFICATE_PATH', patch.https.certificatePath);
+        assign(output, 'XPOD_ACME_CERTIFICATE_KEY_PATH', patch.https.certificateKeyPath);
         assign(output, 'XPOD_ACME_RENEW_BEFORE_DAYS', numberString(patch.https.renewBeforeDays));
     }
     if (patch.p2p) {
@@ -67,19 +81,38 @@ function environmentPatch(patch, current) {
         assign(output, 'XPOD_P2P_FALLBACK_POLICY', patch.p2p.fallbackPolicy);
     }
     if (patch.tunnelProfiles) {
-        assign(output, 'XPOD_TUNNEL_ACTIVE_PROFILE_ID', patch.tunnelProfiles.activeProfileId);
+        // An empty selection is the explicit off decision, stored as its own value so the
+        // runtime can tell it apart from "never configured".
+        assign(output, 'XPOD_TUNNEL_ACTIVE_PROFILE_ID', patch.tunnelProfiles.activeProfileId === ''
+            ? TunnelProfiles_1.TUNNEL_ACTIVE_PROFILE_NONE
+            : patch.tunnelProfiles.activeProfileId);
         if (patch.tunnelProfiles.profiles) {
-            const serialized = patch.tunnelProfiles.profiles.map(({ credential, ...profile }) => profile);
+            const serialized = patch.tunnelProfiles.profiles.map(({ credential, publicEndpoint, ...profile }) => ({
+                ...profile,
+                // Canonical field name: the runtime reads publicUrl.
+                ...(profile.publicUrl ?? publicEndpoint ? { publicUrl: profile.publicUrl ?? publicEndpoint } : {}),
+            }));
             output.XPOD_TUNNEL_PROFILES = JSON.stringify(serialized);
-            for (const profile of patch.tunnelProfiles.profiles)
-                if (profile.credential !== undefined)
-                    output[tunnelCredentialKey(profile.provider)] = profile.credential;
+            for (const profile of patch.tunnelProfiles.profiles) {
+                if (profile.credential !== undefined && profile.credential !== '') {
+                    output[(0, TunnelProfiles_1.tunnelProfileCredentialEnvKey)(profile.id)] = profile.credential;
+                }
+            }
+            // Credentials of profiles that are gone must go with them.
+            for (const key of Object.keys(current)) {
+                if (!(0, TunnelProviderCatalog_1.isTunnelProfileCredentialEnvKey)(key)) {
+                    continue;
+                }
+                if (!patch.tunnelProfiles.profiles.some((profile) => (0, TunnelProfiles_1.tunnelProfileCredentialEnvKey)(profile.id) === key)) {
+                    removals.add(key);
+                }
+            }
         }
     }
-    return output;
+    return { envPatch: output, removals: [...removals] };
 }
 function parseProfiles(raw, env) {
-    if (!raw)
+    if (raw === undefined)
         return [];
     try {
         const values = JSON.parse(raw);
@@ -89,21 +122,44 @@ function parseProfiles(raw, env) {
             if (!value || typeof value !== 'object' || Array.isArray(value))
                 return [];
             const item = value;
-            if (typeof item.id !== 'string' || typeof item.label !== 'string' || !['ngrok', 'cloudflare', 'frp'].includes(String(item.provider)))
+            if (typeof item.id !== 'string' || typeof item.label !== 'string' || !(0, TunnelProviderCatalog_1.isTunnelProviderId)(item.provider))
                 return [];
             const provider = item.provider;
-            return [{ id: item.id, provider, label: item.label, ...(typeof item.publicEndpoint === 'string' ? { publicEndpoint: item.publicEndpoint } : {}), credentialConfigured: Boolean(env[tunnelCredentialKey(provider)]), ...(plainStringRecord(item.parameters) ? { parameters: item.parameters } : {}) }];
+            const publicUrl = firstString(item.publicUrl, item.publicEndpoint);
+            const credentialKey = resolveCredentialKey(item.id, provider, env);
+            return [{
+                    id: item.id,
+                    provider,
+                    label: item.label,
+                    ...(publicUrl ? { publicUrl } : {}),
+                    credentialConfigured: Boolean(env[credentialKey]),
+                    ...(plainStringRecord(item.parameters) ? { parameters: item.parameters } : {}),
+                }];
         });
     }
     catch {
         return [];
     }
 }
+/** Profile-scoped credential first; a provider-global key still serves legacy setups. */
+function resolveCredentialKey(profileId, provider, env) {
+    const scopedKey = (0, TunnelProfiles_1.tunnelProfileCredentialEnvKey)(profileId);
+    if (env[scopedKey])
+        return scopedKey;
+    const legacyKey = (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(provider)?.legacyCredentialEnvKey;
+    return legacyKey && env[legacyKey] ? legacyKey : scopedKey;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
 function splitList(value) { return value?.split(',').map((item) => item.trim()).filter(Boolean) ?? []; }
 function positiveInteger(value, fallback) { const parsed = Number(value); return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback; }
 function dnsCredential(env, provider) { return env[dnsCredentialKey(provider)]; }
 function dnsCredentialKey(provider) { return provider === 'tencent' ? 'XPOD_TENCENT_DNS_TOKEN' : provider === 'cloudflare' ? 'CLOUDFLARE_API_TOKEN' : 'XPOD_DNS_PROVIDER_TOKEN'; }
-function tunnelCredentialKey(provider) { return provider === 'ngrok' ? 'NGROK_AUTHTOKEN' : provider === 'cloudflare' ? 'CLOUDFLARE_TUNNEL_TOKEN' : 'FRP_TUNNEL_TOKEN'; }
 function p2pFallback(value) { return value === 'never' || value === 'prefer-p2p' ? value : 'when-direct-unavailable'; }
 function plainStringRecord(value) { return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every((item) => typeof item === 'string'); }
 function boolString(value) { return value === undefined ? undefined : String(value); }

package/dist/api/runtime.d.ts

@@ -18,4 +18,13 @@ export interface ApiServiceHandle {
     stop: () => Promise<void>;
 }
 export declare function autoProvisionFirstRunLocal(config: ApiContainerConfig, logger: ReturnType<typeof getLoggerFor>): Promise<ApiContainerConfig>;
+/**
+ * Port a managed tunnel forwards to.
+ *
+ * It must be the Gateway's ingress listener rather than the gateway port itself:
+ * a tunnel terminating on the gateway port reaches the Gateway from loopback and
+ * would let forwarded remote requests inherit local trust. Falls back to the
+ * historical gateway port only when no ingress listener was provisioned.
+ */
+export declare function resolveTunnelIngressPort(env?: NodeJS.ProcessEnv): number;
 export declare function startApiService(options?: StartApiServiceOptions): Promise<ApiServiceHandle>;

package/dist/api/runtime.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.autoProvisionFirstRunLocal = autoProvisionFirstRunLocal;
+exports.resolveTunnelIngressPort = resolveTunnelIngressPort;
 exports.startApiService = startApiService;
 const awilix_1 = require("awilix");
 const global_logger_factory_1 = require("global-logger-factory");
@@ -314,6 +315,19 @@ async function reconcileLocalOwnerRoles(container, config, logger) {
         logger.error(`Failed to reconcile local owner roles: ${error}`);
     }
 }
+/**
+ * Port a managed tunnel forwards to.
+ *
+ * It must be the Gateway's ingress listener rather than the gateway port itself:
+ * a tunnel terminating on the gateway port reaches the Gateway from loopback and
+ * would let forwarded remote requests inherit local trust. Falls back to the
+ * historical gateway port only when no ingress listener was provisioned.
+ */
+function resolveTunnelIngressPort(env = process.env) {
+    const raw = env.XPOD_GATEWAY_INGRESS_PORT ?? env.XPOD_MAIN_PORT ?? env.CSS_PORT ?? env.PORT ?? '3000';
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 3000;
+}
 async function startBackgroundServices(container, logger) {
     try {
         const localNetworkManager = container.resolve('localNetworkManager', { allowUnregistered: true });
@@ -338,10 +352,9 @@ async function startBackgroundServices(container, logger) {
         const localTunnelProvider = container.resolve('localTunnelProvider', { allowUnregistered: true });
         if (localTunnelProvider) {
             logger.info('Starting local tunnel provider...');
-            const localPort = Number.parseInt(process.env.XPOD_MAIN_PORT ?? process.env.CSS_PORT ?? process.env.PORT ?? '3000', 10);
             const config = await localTunnelProvider.setup({
                 subdomain: 'local',
-                localPort: Number.isFinite(localPort) && localPort > 0 ? localPort : 3000,
+                localPort: resolveTunnelIngressPort(),
                 localProtocol: 'http',
             });
             await localTunnelProvider.start(config);

package/dist/api/service/AiClientConfigurationService.d.ts

@@ -1,4 +1,4 @@
-import { type AiClientModelReference } from '@undefineds.co/ai-connections-core/client-config';
+import { type AiClientModelReference } from '@undefineds.co/ai-connections/client-config';
 import type { AuthContext } from '../auth/AuthContext';
 export type AiClientId = 'codex' | 'claude-code' | 'pi' | 'codebuddy';
 export interface AiClientConfigurationCapabilityDescriptor {

package/dist/api/service/AiClientConfigurationService.js

@@ -10,7 +10,7 @@ const node_crypto_1 = require("node:crypto");
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
-const client_config_1 = require("@undefineds.co/ai-connections-core/client-config");
+const client_config_1 = require("@undefineds.co/ai-connections/client-config");
 const PLAN_SECRET_PLACEHOLDER = '[redacted]';
 const MANUAL_INSTRUCTIONS = 'Manual client setup is available when this host cannot safely write local coding-client files.';
 const CLIENT_LABELS = {

package/dist/cli/commands/start.d.ts

@@ -10,12 +10,30 @@ interface StartArgs {
     seedConfig?: string;
 }
 export declare const startCommand: CommandModule<object, StartArgs>;
+/**
+ * Where remote-forwarded traffic lands on this machine.
+ *
+ * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
+ * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
+ * forwards to a specific port cannot follow us somewhere else.
+ */
+export declare function resolveIngressPort(config: {
+    tunnelProfiles?: Array<{
+        id: string;
+        provider: string;
+        credentialEnvKey?: string;
+        credentialConfigured?: boolean;
+    }>;
+    tunnelActiveProfileId?: string;
+}, mainPort: number): Promise<number>;
 export declare function resolveCliOidcIssuer(env: Record<string, string | undefined>, provisionedIssuer?: string, edition?: string): string | undefined;
-export declare function resolveManagedEdgeAgentConfig(config: Pick<ReturnType<typeof loadConfigFromEnv>, 'cloudApiEndpoint' | 'nodeId' | 'nodeToken'>, gatewayPort: number): {
+export declare function resolveManagedEdgeAgentConfig(config: Pick<ReturnType<typeof loadConfigFromEnv>, 'cloudApiEndpoint' | 'nodeId' | 'nodeToken'>, gatewayPort: number, ingressPort?: number, runtimeEnv?: Record<string, string | undefined>): {
     signalEndpoint: string;
     nodeId: string;
     nodeToken: string;
     targetBaseUrl: string;
+    lanBaseUrl: string;
+    p2pEnabled: boolean;
 } | undefined;
 export declare function resolveChildDatabaseUrl(value: string, childCwd: string): string;
 export declare function resolveCanonicalRuntimeBaseUrl(provisionedPublicUrl: string | undefined, configuredBaseUrl: string | undefined, localFallbackUrl: string): string;

package/dist/cli/commands/start.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startCommand = void 0;
+exports.resolveIngressPort = resolveIngressPort;
 exports.resolveCliOidcIssuer = resolveCliOidcIssuer;
 exports.resolveManagedEdgeAgentConfig = resolveManagedEdgeAgentConfig;
 exports.resolveChildDatabaseUrl = resolveChildDatabaseUrl;
@@ -15,6 +16,7 @@ const fs_1 = __importDefault(require("fs"));
 const global_logger_factory_1 = require("global-logger-factory");
 const supervisor_1 = require("../../supervisor");
 const runtime_1 = require("../../runtime");
+const SakuraFrpTunnelProvider_1 = require("../../tunnel/SakuraFrpTunnelProvider");
 const css_process_1 = require("../../runtime/css-process");
 const oidc_issuer_1 = require("../../runtime/oidc-issuer");
 const AuthMode_1 = require("../../authorization/AuthMode");
@@ -70,6 +72,10 @@ exports.startCommand = {
                 process.env[key] ??= value;
             }
             process.env.XPOD_ENV_FILE = envPath;
+            // The settings API persists to XPOD_ENV_PATH (falling back to `<cwd>/.env.local`).
+            // Without this, a deployment started with `-e custom.env` saved its configuration
+            // into a file the runtime never reads.
+            process.env.XPOD_ENV_PATH ??= envPath;
         }
         else if (argv.env || process.env.XPOD_ENV_FILE) {
             console.warn(`Env file not found: ${envPath}`);
@@ -101,6 +107,19 @@ exports.startCommand = {
         const cssPort = await (0, runtime_1.getFreePortForWildcard)(requestedCssPort);
         const requestedApiPort = resolveServicePort(process.env.API_PORT, cssPort + 1, new Set([mainPort, cssPort]));
         const apiPort = await (0, runtime_1.getFreePortForWildcard)(requestedApiPort);
+        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so
+        // its origin is a dedicated ingress port instead of the gateway port: the Gateway
+        // never treats requests accepted there as local. An explicit override is honoured;
+        // otherwise the OS assigns a loopback port, because neighbouring ports may already
+        // belong to another service this deployment planned.
+        // The port is a fact of whichever tunnel forwards to us: an explicit override pins it,
+        // and the SakuraFrp console's own 本地端口 is read back from the provider, so the
+        // operator never types the same number twice. Only an unmanaged ingress is ephemeral.
+        // A pinned port is taken as-is: silently moving it would leave the tunnel pointing at a
+        // port nobody listens on.
+        const ingressPort = await resolveIngressPort(provisionedConfig, mainPort);
+        // Published so the API can tell the operator which address a tunnel must forward to.
+        process.env.XPOD_GATEWAY_INGRESS_PORT = String(ingressPort);
         const runtimeRoot = path_1.default.join(process.cwd(), '.xpod/runtime/legacy-css');
         const identityDbUrl = resolveChildDatabaseUrl(process.env.CSS_IDENTITY_DB_URL ?? process.env.DATABASE_URL ?? 'sqlite:./data/identity.sqlite', runtimeRoot);
         process.env.CSS_IDENTITY_DB_URL = identityDbUrl;
@@ -135,7 +154,7 @@ exports.startCommand = {
             authMode,
             externalOidcIssuer,
         });
-        const managedEdge = resolveManagedEdgeAgentConfig(provisionedConfig, mainPort);
+        const managedEdge = resolveManagedEdgeAgentConfig(provisionedConfig, mainPort, ingressPort, process.env);
         const cssArgs = (0, css_process_1.buildCssArgs)({
             cssBinary: '__internal-css',
             configPath: cssRuntimeConfig.configPath,
@@ -169,6 +188,7 @@ exports.startCommand = {
                 apiPort,
                 mainPort,
                 cssPort,
+                ingressPort,
                 baseUrl,
                 rdfIndexPath,
                 authMode,
@@ -180,6 +200,7 @@ exports.startCommand = {
             exitOnStop: true,
             baseUrl,
             internalAdminAuthSecret: gatewayAdminProxyAuthSecret,
+            ingressPort,
         });
         proxy.setTargets({
             css: `http://localhost:${cssPort}`,
@@ -195,8 +216,9 @@ exports.startCommand = {
                 nodeToken: managedEdge.nodeToken,
                 baseUrl,
                 p2p: {
-                    enabled: true,
+                    enabled: managedEdge.p2pEnabled,
                     targetBaseUrl: managedEdge.targetBaseUrl,
+                    lanBaseUrl: managedEdge.lanBaseUrl,
                 },
             });
         }
@@ -210,20 +232,64 @@ exports.startCommand = {
         process.on('SIGINT', () => shutdown('SIGINT'));
     },
 };
+/**
+ * Where remote-forwarded traffic lands on this machine.
+ *
+ * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
+ * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
+ * forwards to a specific port cannot follow us somewhere else.
+ */
+async function resolveIngressPort(config, mainPort) {
+    const explicit = process.env.XPOD_GATEWAY_INGRESS_PORT?.trim();
+    if (explicit) {
+        return await (0, runtime_1.requireFreePortForWildcard)(Number.parseInt(explicit, 10));
+    }
+    const active = config.tunnelProfiles?.find((profile) => profile.id === config.tunnelActiveProfileId)
+        ?? config.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
+    if (active?.provider === 'sakura_frp') {
+        const credential = active.credentialEnvKey
+            ? process.env[active.credentialEnvKey] ?? process.env.SAKURA_TUNNEL_TOKEN
+            : process.env.SAKURA_TUNNEL_TOKEN;
+        const assigned = await (0, SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort)(credential);
+        if (assigned && assigned !== mainPort) {
+            return await (0, runtime_1.requireFreePortForWildcard)(assigned);
+        }
+    }
+    // The operator copies this address into a provider console, so it has to survive
+    // restarts instead of being a fresh OS-assigned port every time.
+    const stateFile = path_1.default.join(process.cwd(), '.xpod', 'runtime', 'ingress-port');
+    const stable = await (0, runtime_1.resolveStableLoopbackPort)(stateFile);
+    if (stable.changed) {
+        (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The ingress port changed to ${stable.port}; update the tunnel console if it still forwards to the previous port`);
+    }
+    return stable.port;
+}
 function resolveCliOidcIssuer(env, provisionedIssuer, edition) {
     return (0, oidc_issuer_1.resolveExternalOidcIssuer)(env)
         ?? (0, oidc_issuer_1.resolveExternalOidcIssuer)({ SOLID_OIDC_ISSUER: provisionedIssuer })
         ?? (edition === 'local' ? oidc_issuer_1.DEFAULT_LOCAL_OIDC_ISSUER : undefined);
 }
-function resolveManagedEdgeAgentConfig(config, gatewayPort) {
+function resolveManagedEdgeAgentConfig(config, gatewayPort, ingressPort, runtimeEnv = {}) {
     if (!config.cloudApiEndpoint || !config.nodeId || !config.nodeToken) {
         return undefined;
     }
+    const gatewayBaseUrl = `http://127.0.0.1:${gatewayPort}/`;
+    // The settings page owns these two decisions; the managed node identity only supplies
+    // the signal endpoint they run against.
+    const declaredSignalService = runtimeEnv.XPOD_P2P_SIGNAL_SERVICE?.trim();
+    const p2pDisabled = runtimeEnv.XPOD_P2P_ENABLED?.trim().toLowerCase() === 'false';
     return {
-        signalEndpoint: new URL('/v1/signal', config.cloudApiEndpoint).toString(),
+        signalEndpoint: declaredSignalService
+            || new URL('/v1/signal', config.cloudApiEndpoint).toString(),
         nodeId: config.nodeId,
         nodeToken: config.nodeToken,
-        targetBaseUrl: `http://127.0.0.1:${gatewayPort}/`,
+        // Forwarded peer traffic enters through the ingress listener, which never counts
+        // as local. LAN clients keep addressing the gateway listener, which they can reach.
+        targetBaseUrl: ingressPort === undefined ? gatewayBaseUrl : `http://127.0.0.1:${ingressPort}/`,
+        lanBaseUrl: gatewayBaseUrl,
+        // Peer-to-peer transport is off by default unless the deployment asked for it; an
+        // explicit false must actually stop it.
+        p2pEnabled: !p2pDisabled && runtimeEnv.XPOD_P2P_ENABLED?.trim().toLowerCase() === 'true',
     };
 }
 function resolveChildDatabaseUrl(value, childCwd) {

package/dist/components/context.jsonld

@@ -1967,6 +1967,15 @@
           "options_locations": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
           },
+          "options_resolveAddresses": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses"
+          },
+          "options_headRequest": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest"
+          },
+          "options_maxRedirects": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects"
+          },
           "repository": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_repository"
           },
@@ -1981,6 +1990,15 @@
           },
           "locations": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
+          },
+          "resolveAddresses": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses"
+          },
+          "headRequest": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest"
+          },
+          "maxRedirects": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects"
           }
         }
       },
@@ -2029,6 +2047,9 @@
           "options_p2pTargetBaseUrl": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
           },
+          "options_p2pLanBaseUrl": {
+            "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+          },
           "options_p2pLabel": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel"
           },
@@ -2118,6 +2139,9 @@
           "p2pTargetBaseUrl": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
           },
+          "p2pLanBaseUrl": {
+            "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+          },
           "p2pLabel": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel"
           },
@@ -2959,6 +2983,9 @@
           "options_cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
           },
+          "options_connectTimeoutMs": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
+          },
           "tunnelToken": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_tunnelToken"
           },
@@ -2967,6 +2994,9 @@
           },
           "cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
+          },
+          "connectTimeoutMs": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
           }
         }
       },

package/dist/edge/EdgeNodeAgent.d.ts

@@ -47,6 +47,12 @@ export interface EdgeNodeAgentOptions {
     p2p?: {
         enabled?: boolean | string;
         targetBaseUrl: string | URL;
+        /**
+         * Address this node advertises as its LAN route. Defaults to `targetBaseUrl`,
+         * and must be set when the forwarding target is a loopback-only listener that
+         * other devices on the LAN cannot reach.
+         */
+        lanBaseUrl?: string | URL;
         label?: string;
         host?: string;
         address?: string;

package/dist/edge/EdgeNodeAgent.js

@@ -244,7 +244,7 @@ class EdgeNodeAgent {
         if (!p2p || this.normalizeBoolean(p2p.enabled) === false) {
             return [];
         }
-        const endpoint = this.resolveLanGatewayEndpoint(p2p.targetBaseUrl);
+        const endpoint = this.resolveLanGatewayEndpoint(p2p.lanBaseUrl ?? p2p.targetBaseUrl);
         if (!endpoint) {
             return [];
         }

package/dist/edge/EdgeNodeAgentInitializer.d.ts

@@ -16,6 +16,8 @@ export interface EdgeNodeAgentInitializerOptions {
     intervalMs?: number | string;
     p2pEnabled?: boolean | string;
     p2pTargetBaseUrl?: string;
+    /** LAN-facing address; defaults to `p2pTargetBaseUrl` inside the agent. */
+    p2pLanBaseUrl?: string;
     p2pLabel?: string;
     p2pAcceptIntervalMs?: number | string;
     p2pConnectTimeoutMs?: number | string;

package/dist/edge/EdgeNodeAgentInitializer.js

@@ -86,6 +86,7 @@ class EdgeNodeAgentInitializer extends community_server_1.Initializer {
                 p2p: {
                     enabled: true,
                     targetBaseUrl: options.p2pTargetBaseUrl,
+                    ...(options.p2pLanBaseUrl ? { lanBaseUrl: options.p2pLanBaseUrl } : {}),
                     label: options.p2pLabel,
                     acceptIntervalMs: this.normalizePositiveInteger(options.p2pAcceptIntervalMs),
                     connectTimeoutMs: this.normalizePositiveInteger(options.p2pConnectTimeoutMs),

package/dist/edge/EdgeNodeAgentInitializer.jsonld

@@ -185,6 +185,19 @@
             ]
           }
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "LAN-facing address; defaults to `p2pTargetBaseUrl` inside the agent."
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel",
           "range": {
@@ -555,6 +568,12 @@
                 "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
               }
             },
+            {
+              "keyRaw": "p2pLanBaseUrl",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+              }
+            },
             {
               "keyRaw": "p2pLabel",
               "value": {