@undefineds.co/xpod 0.4.19 → 0.4.25

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>;

package/dist/runtime/ingress-port.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngressPortConflictError = void 0;
+exports.defaultIngressPortDeps = defaultIngressPortDeps;
+exports.assertUsableIngressPort = assertUsableIngressPort;
+exports.parseExplicitIngressPort = parseExplicitIngressPort;
+exports.resolveIngressPort = resolveIngressPort;
+const global_logger_factory_1 = require("global-logger-factory");
+const port_finder_1 = require("./port-finder");
+const ingress_occupant_1 = require("./ingress-occupant");
+const TunnelDeclaredOrigin_1 = require("../tunnel/TunnelDeclaredOrigin");
+const TunnelProviderCatalog_1 = require("../tunnel/TunnelProviderCatalog");
+/** A strict port that could not be taken: the occupant is named, and nothing was signalled. */
+class IngressPortConflictError extends Error {
+    constructor(port, occupant) {
+        super(`tunnel entry port ${port} is already in use by ${occupant}`);
+        this.port = port;
+        this.occupant = occupant;
+        this.name = 'IngressPortConflictError';
+    }
+}
+exports.IngressPortConflictError = IngressPortConflictError;
+function defaultIngressPortDeps() {
+    const logger = (0, global_logger_factory_1.getLoggerFor)('IngressPort');
+    return {
+        findDefaultPort: port_finder_1.findGatewayIngressPort,
+        isFree: port_finder_1.isFreePortForWildcard,
+        identifyOccupants: (port) => (0, ingress_occupant_1.identifyIngressPortOccupants)(port).description,
+        readDeclaredOrigin: async (profile, options) => await (0, TunnelDeclaredOrigin_1.readDeclaredIngressOrigin)(profile, {
+            env: options.env,
+            active: options.active,
+        }),
+        logger: {
+            info: (message) => logger.info(message),
+            warn: (message) => logger.warn(message),
+        },
+    };
+}
+/**
+ * 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.
+ */
+function assertUsableIngressPort(port, options) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new Error(`${options.label} is not a usable port (expected 1-65535); `
+            + 'a tunnel origin has to be a real port number');
+    }
+    if (port < 1024) {
+        throw new Error(`${options.label} is a privileged port (1-1023); this runtime does not take root `
+            + 'to bind a tunnel origin, so point the tunnel at a port at or above 1024');
+    }
+    if (options.reservedPorts?.has(port)) {
+        throw new Error(`${options.label} is a port this runtime already serves (gateway/CSS/API); `
+            + 'the tunnel entry has to be its own listener, or forwarded traffic would land on another service');
+    }
+}
+/** Reads the explicit pin strictly: present but malformed is an error, not an absent value. */
+function parseExplicitIngressPort(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(trimmed)) {
+        throw new Error(`XPOD_GATEWAY_INGRESS_PORT="${trimmed}" is not a valid port number (expected 1-65535)`);
+    }
+    return Number.parseInt(trimmed, 10);
+}
+async function resolveIngressPort(request) {
+    const deps = { ...defaultIngressPortDeps(), ...request.deps };
+    const env = request.env ?? process.env;
+    const reservedPorts = new Set(request.reservedPorts ?? []);
+    const profiles = request.profiles ?? [];
+    const activeProfileId = request.activeProfileId?.trim();
+    const active = activeProfileId && activeProfileId !== 'none'
+        ? profiles.find((profile) => profile.id === activeProfileId)
+        : undefined;
+    const explicit = parseExplicitIngressPort(env.XPOD_GATEWAY_INGRESS_PORT);
+    if (explicit !== undefined) {
+        assertUsableIngressPort(explicit, {
+            label: `XPOD_GATEWAY_INGRESS_PORT=${explicit}`,
+            reservedPorts,
+        });
+        await requireFree(explicit, `XPOD_GATEWAY_INGRESS_PORT=${explicit}`, deps);
+        deps.logger.info(`Tunnel entry pinned to ${explicit} by XPOD_GATEWAY_INGRESS_PORT `
+            + '(a provider console value is not read while an explicit pin is present)');
+        return { port: explicit, source: 'explicit', inactiveDeclarations: [] };
+    }
+    const inactiveDeclarations = await readInactiveConsoleDeclarations({ profiles, active, env, deps });
+    for (const declaration of inactiveDeclarations) {
+        deps.logger.warn(`profile ${declaration.profileId} (${declaration.provider}) is not active, but its console declares `
+            + `tunnel origin ${declaration.port} (${declaration.readBack}); `
+            + `the active profile is ${active?.id ?? 'none'}, so its entry decides this runtime's listener`);
+    }
+    const activeDescriptor = active ? (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(active.provider) : undefined;
+    if (active && activeDescriptor?.originOwner === 'console') {
+        const read = await deps.readDeclaredOrigin(active, { env, active: true });
+        if (read.origin) {
+            const label = `the ${activeDescriptor.label} console's declared tunnel origin ${read.origin.port}`;
+            assertUsableIngressPort(read.origin.port, { label, reservedPorts });
+            await requireFree(read.origin.port, label, deps);
+            if (read.origin.scheme && read.origin.scheme !== 'http') {
+                deps.logger.warn(`${activeDescriptor.label} declares the origin as ${read.origin.scheme}://localhost:${read.origin.port}, `
+                    + `but this runtime's tunnel entry speaks plain HTTP; the port is adopted, the scheme is not `
+                    + '(terminate TLS in the provider, or point the console at http://)');
+            }
+            deps.logger.info(`Adopting the ${activeDescriptor.label} console's tunnel origin ${read.origin.port} `
+                + `(${read.origin.readBack}); the operator does not have to edit the console`);
+            return {
+                port: read.origin.port,
+                source: 'console-declared',
+                declared: {
+                    profileId: active.id,
+                    provider: activeDescriptor.id,
+                    port: read.origin.port,
+                    readBack: read.origin.readBack,
+                    ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+                },
+                inactiveDeclarations,
+            };
+        }
+        // The console owns the number, so the runtime cannot invent a different one and still be
+        // reachable. The declaration is unreadable here, which is reported loudly; an explicit pin
+        // (handled above) is the deterministic way out.
+        deps.logger.warn(`the ${activeDescriptor.label} console's tunnel origin could not be read `
+            + `(${read.error ?? 'no reason reported'}); this runtime will serve the default tunnel entry `
+            + 'instead, and the tunnel provider will report its own failure. '
+            + 'Pin XPOD_GATEWAY_INGRESS_PORT to decide the entry explicitly');
+    }
+    const port = await deps.findDefaultPort(request.mainPort);
+    deps.logger.info(`Tunnel entry ${port} chosen from the gateway port ${request.mainPort} (gateway+3..+9, first free port)`);
+    return { port, source: 'gateway-default', inactiveDeclarations };
+}
+/** A strict port is taken as-is or not at all; the occupant is named, never signalled. */
+async function requireFree(port, label, deps) {
+    if (await deps.isFree(port)) {
+        return;
+    }
+    const occupant = deps.identifyOccupants(port);
+    throw new IngressPortConflictError(port, occupant);
+}
+async function readInactiveConsoleDeclarations(input) {
+    const declarations = [];
+    for (const profile of input.profiles) {
+        if (profile.id === input.active?.id) {
+            continue;
+        }
+        if ((0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(profile.provider)?.originOwner !== 'console') {
+            continue;
+        }
+        const read = await input.deps.readDeclaredOrigin(profile, { env: input.env, active: false });
+        if (read.origin) {
+            declarations.push({
+                profileId: profile.id,
+                provider: profile.provider,
+                port: read.origin.port,
+                readBack: read.origin.readBack,
+                ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+            });
+        }
+    }
+    return declarations;
+}
+//# sourceMappingURL=ingress-port.js.map

package/dist/runtime/lifecycle.js

@@ -10,19 +10,30 @@ const package_root_1 = require("./package-root");
 const bootstrap_1 = require("./bootstrap");
 const RedisClientLifecycle_1 = require("../storage/redis/RedisClientLifecycle");
 const DEFAULT_SERVICE_STOP_TIMEOUT_MS = 5_000;
-async function stopWithTimeout(name, stop, timeoutMs) {
+async function stopWithTimeout(name, stop, timeoutMs, onDrainTimeout) {
     let timeout;
+    const pending = stop();
+    const deadline = new Error(`${name} stop timed out after ${timeoutMs}ms`);
     try {
         await Promise.race([
-            stop(),
+            pending,
             new Promise((_, reject) => {
                 timeout = setTimeout(() => {
-                    reject(new Error(`${name} stop timed out after ${timeoutMs}ms`));
+                    reject(deadline);
                 }, timeoutMs);
                 timeout.unref();
             }),
         ]);
     }
+    catch (error) {
+        if (error !== deadline || !onDrainTimeout) {
+            throw error;
+        }
+        onDrainTimeout(deadline);
+        // A deadline is diagnostic for storage consumers. It cannot release their
+        // shared connections while a writer/deletion callback is still running.
+        await pending;
+    }
     finally {
         if (timeout) {
             clearTimeout(timeout);
@@ -120,6 +131,7 @@ async function startGatewayRuntime({ state, host, supervisor, shutdownHandler, g
     return gateway;
 }
 async function stopRuntimeServices({ services, supervisor, logger, host, state, unregisterSocketOrigins, closeIdentityConnections, restoreRuntimeEnv, stopTimeoutMs = DEFAULT_SERVICE_STOP_TIMEOUT_MS, }) {
+    const storageStopErrors = [];
     try {
         if (services.gateway) {
             await stopWithTimeout('gateway', () => services.gateway.stop(), stopTimeoutMs);
@@ -131,21 +143,26 @@ async function stopRuntimeServices({ services, supervisor, logger, host, state,
     }
     try {
         if (services.apiService) {
-            await stopWithTimeout('api', () => services.apiService.stop(), stopTimeoutMs);
+            await stopWithTimeout('api', () => services.apiService.stop(), stopTimeoutMs, (error) => logger.warn(`API is still draining; preserving shared storage: ${String(error)}`));
             supervisor.setStatus('api', 'stopped');
         }
     }
     catch (error) {
         logger.warn(`Failed to stop api: ${String(error)}`);
+        storageStopErrors.push(error);
     }
     try {
         if (services.cssApp) {
-            await stopWithTimeout('css', () => services.cssApp.stop(), stopTimeoutMs);
+            await stopWithTimeout('css', () => services.cssApp.stop(), stopTimeoutMs, (error) => logger.warn(`CSS is still draining; preserving shared storage: ${String(error)}`));
             supervisor.setStatus('css', 'stopped');
         }
     }
     catch (error) {
         logger.warn(`Failed to stop css: ${String(error)}`);
+        storageStopErrors.push(error);
+    }
+    if (storageStopErrors.length) {
+        throw new AggregateError(storageStopErrors, 'Data services did not stop; shared storage remains open');
     }
     await (0, RedisClientLifecycle_1.closeManagedRedisClients)();
     if (state.sockets.css) {

package/dist/runtime/local-secret-file.d.ts

@@ -0,0 +1,9 @@
+export type LocalSecretPurpose = 'gateway-locator-secret' | 'secret-cell-root-key';
+export declare function localSecretPathForDatabase(databasePath: string, purpose: LocalSecretPurpose): string;
+/** Publish complete private key files without replacing an existing identity. */
+export declare function readOrCreateLocalSecret(options: {
+    databasePath: string;
+    purpose: LocalSecretPurpose;
+    label: string;
+    isValid: (value: string) => boolean;
+}): string;

package/dist/runtime/local-secret-file.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localSecretPathForDatabase = localSecretPathForDatabase;
+exports.readOrCreateLocalSecret = readOrCreateLocalSecret;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SECRET_BYTES = 32;
+const SECRET_FILE_MODE = 0o600;
+const SECRET_DIR_MODE = 0o700;
+function localSecretPathForDatabase(databasePath, purpose) {
+    return node_path_1.default.join(node_path_1.default.dirname(databasePath), '.xpod', 'secrets', purpose);
+}
+/** Publish complete private key files without replacing an existing identity. */
+function readOrCreateLocalSecret(options) {
+    const { label } = options;
+    const filePath = localSecretPathForDatabase(options.databasePath, options.purpose);
+    const privateRoot = node_path_1.default.dirname(options.databasePath);
+    const dirPath = node_path_1.default.dirname(filePath);
+    try {
+        preparePrivateDirectoryPath(privateRoot, dirPath, label);
+    }
+    catch (error) {
+        throw new Error(`Failed to prepare ${label} directory at ${dirPath}: ${error.message}`, {
+            cause: error,
+        });
+    }
+    if (!node_fs_1.default.existsSync(filePath)) {
+        publishNewSecret(filePath, options.purpose, label);
+    }
+    const secret = readExistingSecret(filePath, label);
+    if (!options.isValid(secret)) {
+        throw new Error(`${label} file at ${filePath} is invalid; refusing to replace it automatically.`);
+    }
+    return secret;
+}
+function publishNewSecret(filePath, purpose, label) {
+    const dirPath = node_path_1.default.dirname(filePath);
+    const tempPath = node_path_1.default.join(dirPath, `.${purpose}.${process.pid}.${(0, node_crypto_1.randomBytes)(8).toString('hex')}.tmp`);
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(tempPath, 'wx', SECRET_FILE_MODE);
+        node_fs_1.default.writeFileSync(fd, `${(0, node_crypto_1.randomBytes)(SECRET_BYTES).toString('base64url')}\n`, { encoding: 'utf8' });
+        node_fs_1.default.fsyncSync(fd);
+        node_fs_1.default.closeSync(fd);
+        fd = undefined;
+        node_fs_1.default.linkSync(tempPath, filePath);
+        fsyncDirectory(dirPath);
+    }
+    catch (error) {
+        if (!isAlreadyExists(error)) {
+            throw new Error(`Failed to create ${label} file at ${filePath}: ${error.message}`, {
+                cause: error,
+            });
+        }
+    }
+    finally {
+        if (fd !== undefined) {
+            node_fs_1.default.closeSync(fd);
+        }
+        try {
+            node_fs_1.default.unlinkSync(tempPath);
+        }
+        catch (error) {
+            if (!isNotFound(error)) {
+                throw error;
+            }
+        }
+    }
+}
+function readExistingSecret(filePath, label) {
+    const stat = node_fs_1.default.lstatSync(filePath);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`${label} file at ${filePath} must not be a symlink.`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`${label} file at ${filePath} must be a regular file.`);
+    }
+    const fd = node_fs_1.default.openSync(filePath, node_fs_1.default.constants.O_RDONLY | noFollowFlag());
+    try {
+        const fdStat = node_fs_1.default.fstatSync(fd);
+        if (!fdStat.isFile()) {
+            throw new Error(`${label} file at ${filePath} must be a regular file.`);
+        }
+        if (process.platform !== 'win32' && (fdStat.mode & 0o777) !== SECRET_FILE_MODE) {
+            throw new Error(`${label} file at ${filePath} must have mode 0600.`);
+        }
+        return node_fs_1.default.readFileSync(fd, 'utf8').trim();
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+function preparePrivateDirectoryPath(privateRoot, dirPath, label) {
+    const relative = node_path_1.default.relative(privateRoot, dirPath);
+    if (relative.startsWith('..') || node_path_1.default.isAbsolute(relative)) {
+        throw new Error(`${label} directory must stay under the identity database directory.`);
+    }
+    node_fs_1.default.mkdirSync(privateRoot, { recursive: true });
+    let current = privateRoot;
+    for (const segment of relative.split(node_path_1.default.sep).filter(Boolean)) {
+        current = node_path_1.default.join(current, segment);
+        try {
+            node_fs_1.default.mkdirSync(current, { mode: SECRET_DIR_MODE });
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+        const stat = node_fs_1.default.lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`${label} directory at ${current} must not be a symlink.`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`${label} directory at ${current} must be a directory.`);
+        }
+        if (process.platform !== 'win32' && (stat.mode & 0o777) !== SECRET_DIR_MODE) {
+            throw new Error(`${label} directory at ${current} must have mode 0700.`);
+        }
+    }
+}
+function fsyncDirectory(dirPath) {
+    if (process.platform === 'win32') {
+        return;
+    }
+    const fd = node_fs_1.default.openSync(dirPath, node_fs_1.default.constants.O_RDONLY);
+    try {
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+function noFollowFlag() {
+    return typeof node_fs_1.default.constants.O_NOFOLLOW === 'number' ? node_fs_1.default.constants.O_NOFOLLOW : 0;
+}
+function isAlreadyExists(error) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === 'EEXIST';
+}
+function isNotFound(error) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === 'ENOENT';
+}
+//# sourceMappingURL=local-secret-file.js.map

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

@@ -5,9 +5,21 @@
  * into a provider console and it survives restarts - while staying clear of the block a
  * neighbouring runtime plans for its own services. When the neighbourhood is busy the caller
  * gets an OS-assigned port instead of a stolen one; the runtime reports whichever it got.
+ *
+ * Reserved ports are skipped here too: a group that needs a fixed port has published a
+ * reservation, and a dynamic entry that took it would break that group's tunnel instead of
+ * merely moving its own listener.
+ */
+export declare function findGatewayIngressPort(gatewayPort: number, excluded?: ReadonlySet<number>): Promise<number>;
+/**
+ * The first free port at or above `basePort`.
+ *
+ * Reserved ports are skipped, not merely avoided by convention: a group that needs a fixed port
+ * (the tunnel acceptance's console-owned 5737) publishes a reservation, and every allocator -
+ * the runtime, the test helpers, the integration runners - goes around it instead of racing for
+ * it. That is the difference between "usually fine" and "cannot collide".
  */
-export declare function findGatewayIngressPort(gatewayPort: number): Promise<number>;
-export declare function getFreePort(basePort: number, host?: string, timeoutMs?: number): Promise<number>;
+export declare function getFreePort(basePort: number, host?: string, timeoutMs?: number, excluded?: ReadonlySet<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.
@@ -18,11 +30,8 @@ export declare function getFreePort(basePort: number, host?: string, timeoutMs?:
  * runtime's service.
  */
 export declare function getEphemeralLoopbackPort(): Promise<number>;
-/**
- * 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.
- */
+/** Tests socket availability on all service addresses, including an explicitly reserved port. */
+export declare function isFreePortForWildcard(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Takes exactly this port or fails.
  *
@@ -30,4 +39,10 @@ export declare function getEphemeralLoopbackPort(): Promise<number>;
  * 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>;
+/**
+ * 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 - and a reserved port is skipped either way.
+ */
+export declare function getFreePortForWildcard(basePort: number, timeoutMs?: number, excluded?: ReadonlySet<number>): Promise<number>;