@rynx-ai/daemon 0.1.0 → 0.1.10-beta.2

package/dist/desktop-browser-host-client.js

@@ -0,0 +1,415 @@
+import { DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS, DESKTOP_BROWSER_HOST_PATH, DESKTOP_BROWSER_HOST_PROTOCOL_VERSION, encodeDesktopBrowserHostSurfaceFrame, parseDesktopBrowserHostClientFrame, parseDesktopBrowserHostServerFrame, } from "@rynx-ai/protocol/desktop-browser-host";
+import { WebSocket } from "ws";
+import { ensureDaemonControlEndpoint } from "./control-endpoint.js";
+const CONNECT_TIMEOUT_MS = 5_000;
+const MAX_BUFFERED_BYTES = DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES + DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES;
+/** Open the sole resident daemon's authenticated loopback Desktop Host lease. */
+export async function connectResidentDesktopBrowserHost(options) {
+    options.signal?.throwIfAborted();
+    const hello = parseDesktopBrowserHostClientFrame({
+        type: "desktop.browser.host.hello",
+        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+        hostInstanceId: options.hostInstanceId,
+        capabilities: {
+            semanticPageBinding: options.capabilities.semanticPageBinding,
+            presentation: options.capabilities.presentation,
+            surface: options.capabilities.surface,
+        },
+    });
+    if (hello.type !== "desktop.browser.host.hello") {
+        throw new Error("Desktop Browser Host hello parser returned the wrong frame");
+    }
+    const endpoint = await ensureDaemonControlEndpoint({ signal: options.signal });
+    assertLoopbackOrigin(endpoint.origin);
+    const url = new URL(DESKTOP_BROWSER_HOST_PATH, `${endpoint.origin}/`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const socket = new WebSocket(url, {
+        headers: { "x-rynx-management-token": endpoint.managementToken },
+        handshakeTimeout: CONNECT_TIMEOUT_MS,
+        maxPayload: DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES,
+        perMessageDeflate: false,
+    });
+    const queue = new BoundedCommandQueue(DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS);
+    let lease;
+    let leaseResolve;
+    let leaseReject;
+    const leaseReady = new Promise((resolve, reject) => {
+        leaseResolve = resolve;
+        leaseReject = reject;
+    });
+    let closedResolve;
+    const closed = new Promise((resolve) => {
+        closedResolve = resolve;
+    });
+    let terminalError;
+    let eventSequence = 0;
+    let closing = false;
+    let writerTail = Promise.resolve();
+    const activeRequests = new Map();
+    const abortActiveRequests = (error) => {
+        for (const request of activeRequests.values()) {
+            if (request.timer)
+                clearTimeout(request.timer);
+            request.settled = true;
+            request.controller.abort(error);
+        }
+        activeRequests.clear();
+    };
+    const fail = (error) => {
+        terminalError ??= error;
+        if (!lease)
+            leaseReject(error);
+        queue.close(error);
+        abortActiveRequests(error);
+    };
+    const failConnection = (error, code, reason) => {
+        fail(error);
+        if (socket.readyState < WebSocket.CLOSING)
+            socket.close(code, reason);
+    };
+    const enqueueWrite = (operation) => {
+        const current = writerTail.then(async () => {
+            if (terminalError)
+                throw terminalError;
+            await operation();
+        });
+        writerTail = current.catch(() => undefined);
+        return current.catch((error) => {
+            const failure = asError(error, "Desktop Browser Host output failed");
+            failConnection(failure, 1011, "host output failed");
+            throw failure;
+        });
+    };
+    const onAbort = () => {
+        const error = abortError(options.signal?.reason);
+        failConnection(error, 1000, "aborted");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    socket.on("open", () => {
+        void enqueueWrite(() => sendJson(socket, hello));
+    });
+    socket.on("message", (raw, isBinary) => {
+        if (isBinary) {
+            failConnection(new Error("Desktop Browser Host daemon sent an unexpected binary frame"), 1003, "binary frame unsupported");
+            return;
+        }
+        let frame;
+        try {
+            const bytes = rawDataBytes(raw);
+            if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES) {
+                throw new Error("Desktop Browser Host daemon frame exceeded its bound");
+            }
+            frame = parseDesktopBrowserHostServerFrame(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+        }
+        catch (error) {
+            failConnection(asError(error, "Desktop Browser Host daemon frame was invalid"), 1007, "invalid daemon frame");
+            return;
+        }
+        if (!lease) {
+            if (frame.type !== "desktop.browser.host.lease") {
+                failConnection(new Error("Desktop Browser Host daemon did not begin with a lease"), 1002, "lease required");
+                return;
+            }
+            if (frame.capabilities.semanticPageBinding &&
+                !options.capabilities.semanticPageBinding) {
+                failConnection(new Error("Desktop Browser Host daemon enabled an unadvertised Page binding capability"), 1002, "invalid lease capabilities");
+                return;
+            }
+            if (frame.capabilities.surface === "binary-v1" &&
+                options.capabilities.surface !== "binary-v1") {
+                failConnection(new Error("Desktop Browser Host daemon enabled an unadvertised Surface capability"), 1002, "invalid lease capabilities");
+                return;
+            }
+            lease = frame;
+            leaseResolve(frame);
+            return;
+        }
+        if (frame.type !== "desktop.browser.host.command" || frame.leaseId !== lease.leaseId) {
+            failConnection(new Error("Desktop Browser Host daemon sent a frame outside the active lease"), 1002, "lease mismatch");
+            return;
+        }
+        if (!queue.push(frame)) {
+            failConnection(new Error("Desktop Browser Host command capacity exceeded"), 1013, "command capacity exceeded");
+        }
+    });
+    socket.on("error", (error) => {
+        failConnection(new Error("Desktop Browser Host connection failed", { cause: error }), 1011, "connection failed");
+    });
+    socket.once("close", (code, reason) => {
+        options.signal?.removeEventListener("abort", onAbort);
+        if (!terminalError && !closing) {
+            terminalError = new Error(`Desktop Browser Host lease closed (${code})${reason.length > 0 ? `: ${reason.toString("utf8")}` : ""}`);
+        }
+        if (!lease && terminalError)
+            leaseReject(terminalError);
+        queue.close(terminalError);
+        abortActiveRequests(terminalError ?? new Error("Desktop Browser Host lease closed"));
+        closedResolve();
+    });
+    try {
+        lease = await abortableTimeout(leaseReady, CONNECT_TIMEOUT_MS, options.signal);
+    }
+    catch (error) {
+        if (socket.readyState < WebSocket.CLOSING)
+            socket.close(1000, "lease failed");
+        throw error;
+    }
+    const activeLease = lease;
+    const settle = async (command, value) => {
+        const request = activeRequests.get(command.commandId);
+        if (!request || request.settled) {
+            throw new Error("Desktop Browser Host command is already settled or stale");
+        }
+        if (command.leaseId !== activeLease.leaseId ||
+            request.controller.signal.aborted ||
+            Date.now() >= command.deadlineUnixMilliseconds) {
+            expireRequest(command, request);
+            throw new Error("Desktop Browser Host command deadline expired before settlement");
+        }
+        request.settled = true;
+        if (request.timer)
+            clearTimeout(request.timer);
+        activeRequests.delete(command.commandId);
+        await enqueueWrite(async () => {
+            const frame = parseDesktopBrowserHostClientFrame(value);
+            if (frame.type !== "desktop.browser.host.reply") {
+                throw new Error("Desktop Browser Host reply parser returned the wrong frame");
+            }
+            await sendJson(socket, frame);
+        });
+    };
+    const expireRequest = (command, request) => {
+        if (request.settled)
+            return;
+        request.settled = true;
+        if (request.timer)
+            clearTimeout(request.timer);
+        activeRequests.delete(command.commandId);
+        const error = new Error(`Desktop Browser Host ${command.command.method} deadline expired`);
+        request.controller.abort(error);
+        if (isMutatingCommand(command)) {
+            failConnection(error, 1000, "command deadline expired");
+        }
+    };
+    const requestIterator = queue[Symbol.asyncIterator]();
+    const claimedIterator = {
+        next: async () => {
+            const next = await requestIterator.next();
+            if (next.done)
+                return { done: true, value: undefined };
+            const command = next.value;
+            if (activeRequests.has(command.commandId)) {
+                const error = new Error("Desktop Browser Host daemon repeated a commandId");
+                failConnection(error, 1002, "duplicate command");
+                throw error;
+            }
+            const controller = new AbortController();
+            const remaining = command.deadlineUnixMilliseconds - Date.now();
+            const request = {
+                controller,
+                settled: false,
+            };
+            request.timer = setTimeout(() => expireRequest(command, request), Math.max(1, remaining));
+            request.timer.unref?.();
+            activeRequests.set(command.commandId, request);
+            if (remaining <= 0) {
+                expireRequest(command, request);
+                throw new Error("Desktop Browser Host received an expired command");
+            }
+            return {
+                done: false,
+                value: {
+                    frame: command,
+                    signal: controller.signal,
+                    reply: (result) => settle(command, {
+                        type: "desktop.browser.host.reply",
+                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        leaseId: activeLease.leaseId,
+                        commandId: command.commandId,
+                        ok: true,
+                        result,
+                    }),
+                    reject: (failure) => settle(command, {
+                        type: "desktop.browser.host.reply",
+                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        leaseId: activeLease.leaseId,
+                        commandId: command.commandId,
+                        ok: false,
+                        error: failure,
+                    }),
+                },
+            };
+        },
+    };
+    return {
+        lease: activeLease,
+        closed,
+        [Symbol.asyncIterator]: () => claimedIterator,
+        emit: (event) => enqueueWrite(async () => {
+            const nextSequence = eventSequence + 1;
+            const frame = parseDesktopBrowserHostClientFrame({
+                type: "desktop.browser.host.event",
+                protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                leaseId: activeLease.leaseId,
+                eventSequence: nextSequence,
+                event,
+            });
+            if (frame.type !== "desktop.browser.host.event") {
+                throw new Error("Desktop Browser Host event parser returned the wrong frame");
+            }
+            await sendJson(socket, frame);
+            eventSequence = nextSequence;
+        }),
+        emitSurfaceFrame: (frame) => enqueueWrite(async () => {
+            if (activeLease.capabilities.surface !== "binary-v1") {
+                throw new Error("Desktop Browser Host Surface was not negotiated");
+            }
+            const encoded = encodeDesktopBrowserHostSurfaceFrame({
+                ...frame,
+                leaseId: activeLease.leaseId,
+            });
+            await sendBinary(socket, encoded);
+        }),
+        close: async () => {
+            if (closing)
+                return closed;
+            closing = true;
+            queue.close();
+            abortActiveRequests(new Error("Desktop Browser Host stopped"));
+            if (socket.readyState < WebSocket.CLOSING)
+                socket.close(1000, "host stopped");
+            if (socket.readyState === WebSocket.CLOSED)
+                closedResolve();
+            await closed;
+        },
+    };
+}
+async function sendBinary(socket, bytes) {
+    if (socket.readyState !== WebSocket.OPEN)
+        throw new Error("Desktop Browser Host lease is closed");
+    if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES) {
+        throw new Error("Desktop Browser Host binary frame exceeded its bound");
+    }
+    if (socket.bufferedAmount + bytes.byteLength > MAX_BUFFERED_BYTES) {
+        throw new Error("Desktop Browser Host output buffer exceeded its bound");
+    }
+    await new Promise((resolve, reject) => {
+        socket.send(bytes, { binary: true, compress: false }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+async function sendJson(socket, value) {
+    if (socket.readyState !== WebSocket.OPEN)
+        throw new Error("Desktop Browser Host lease is closed");
+    const bytes = Buffer.from(JSON.stringify(value), "utf8");
+    if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES) {
+        throw new Error("Desktop Browser Host client frame exceeded its bound");
+    }
+    if (socket.bufferedAmount + bytes.byteLength > MAX_BUFFERED_BYTES) {
+        throw new Error("Desktop Browser Host output buffer exceeded its bound");
+    }
+    await new Promise((resolve, reject) => {
+        socket.send(bytes, { binary: false, compress: false }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+class BoundedCommandQueue {
+    capacity;
+    values = [];
+    waiters = [];
+    ended = false;
+    error;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    push(value) {
+        if (this.ended)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value });
+            return true;
+        }
+        if (this.values.length >= this.capacity)
+            return false;
+        this.values.push(value);
+        return true;
+    }
+    close(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.error = error;
+        // Commands are capabilities of this exact socket lease. Never drain a
+        // buffered command after abort/disconnect, even if it was parsed earlier.
+        this.values.length = 0;
+        for (const waiter of this.waiters.splice(0)) {
+            if (error)
+                waiter.reject(error);
+            else
+                waiter.resolve({ done: true, value: undefined });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const value = this.values.shift();
+                if (value)
+                    return Promise.resolve({ done: false, value });
+                if (this.ended) {
+                    return this.error
+                        ? Promise.reject(this.error)
+                        : Promise.resolve({ done: true, value: undefined });
+                }
+                return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+            },
+        };
+    }
+}
+function rawDataBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    throw new Error("Desktop Browser Host received an unsupported WebSocket payload");
+}
+function isMutatingCommand(command) {
+    return command.command.method !== "browser.snapshot" &&
+        command.command.method !== "browser.cdp-endpoint" &&
+        command.command.method !== "page.cdp-endpoint";
+}
+async function abortableTimeout(promise, timeoutMs, signal) {
+    signal?.throwIfAborted();
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(combined.reason));
+        combined.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => combined.removeEventListener("abort", onAbort));
+    });
+}
+function abortError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    return new Error("Desktop Browser Host connection was aborted", { cause: reason });
+}
+function asError(error, message) {
+    return error instanceof Error ? error : new Error(message, { cause: error });
+}
+function assertLoopbackOrigin(origin) {
+    const url = new URL(origin);
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (host !== "localhost" && host !== "127.0.0.1" && host !== "::1") {
+        throw new Error("resident daemon Desktop Browser Host endpoint is not loopback");
+    }
+}

package/dist/direct-runtime-authenticator.d.ts

@@ -0,0 +1,13 @@
+import { type DirectRuntimeServerHello } from "@rynx-ai/protocol/direct-runtime";
+import type { DaemonRuntimeHost, DirectRuntimeAuthenticationResult, DirectRuntimeAuthenticator } from "@rynx-ai/server";
+import type { DaemonInstallationIdentity } from "./installation-id.js";
+import { RemoteRuntimeAccessStore } from "./remote-runtime-access-store.js";
+/** Daemon-side proof verification shared by Direct control and Browser Surface bindings. */
+export declare class DaemonDirectRuntimeAuthenticator implements DirectRuntimeAuthenticator {
+    private readonly identity;
+    private readonly runtime;
+    private readonly access;
+    constructor(identity: DaemonInstallationIdentity, runtime: DaemonRuntimeHost, access: RemoteRuntimeAccessStore);
+    createServerHello({ channelBinding, role, signal, }: Parameters<DirectRuntimeAuthenticator["createServerHello"]>[0]): DirectRuntimeServerHello;
+    authenticate({ channelBinding, role, serverHello, clientAuthenticate, signal, }: Parameters<DirectRuntimeAuthenticator["authenticate"]>[0]): DirectRuntimeAuthenticationResult;
+}

package/dist/direct-runtime-authenticator.js

@@ -0,0 +1,132 @@
+import { createHash, createPublicKey, randomBytes, randomUUID, verify, } from "node:crypto";
+import { DIRECT_RUNTIME_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL, encodeClientAuthenticateCanonical, encodeClientAuthenticateProofPayload, encodeServerHelloCanonical, parseServerAccepted, parseServerHello, } from "@rynx-ai/protocol/direct-runtime";
+/** Daemon-side proof verification shared by Direct control and Browser Surface bindings. */
+export class DaemonDirectRuntimeAuthenticator {
+    identity;
+    runtime;
+    access;
+    constructor(identity, runtime, access) {
+        this.identity = identity;
+        this.runtime = runtime;
+        this.access = access;
+    }
+    createServerHello({ channelBinding, role, signal, }) {
+        signal.throwIfAborted();
+        const status = this.runtime.status();
+        if (status.daemonId !== this.identity.installationId) {
+            throw new Error("daemon Runtime identity does not match its installation identity");
+        }
+        const fields = {
+            type: "server.hello",
+            role,
+            daemonId: status.daemonId,
+            daemonInstanceId: status.daemonInstanceId,
+            identityPublicKey: this.identity.publicKey,
+            nonce: randomBytes(32).toString("base64url"),
+            bindingProtocolVersion: bindingProtocol(role).currentVersion,
+            minimumCompatibleBindingVersion: bindingProtocol(role).minimumCompatibleVersion,
+            coreProtocolVersion: status.coreProtocolVersion,
+            minimumCompatibleCoreVersion: status.minimumCompatibleCoreVersion,
+        };
+        return parseServerHello({
+            ...fields,
+            signature: this.identity.signDirectRuntimeServerHello(channelBinding, fields),
+        });
+    }
+    authenticate({ channelBinding, role, serverHello, clientAuthenticate, signal, }) {
+        signal.throwIfAborted();
+        if (clientAuthenticate.role !== role || serverHello.role !== role) {
+            throw new Error("unsupported Direct Runtime channel role");
+        }
+        if (role !== "control" && clientAuthenticate.mode !== "connect") {
+            throw new Error(`${role === "browser-surface" ? "Browser Surface" : "Browser Inspect"} channels require an existing Direct Runtime grant`);
+        }
+        if (clientAuthenticate.daemonId !== serverHello.daemonId ||
+            clientAuthenticate.daemonInstanceId !== serverHello.daemonInstanceId ||
+            clientAuthenticate.bindingProtocolVersion <
+                serverHello.minimumCompatibleBindingVersion ||
+            clientAuthenticate.bindingProtocolVersion > serverHello.bindingProtocolVersion ||
+            clientAuthenticate.coreProtocolVersion < serverHello.minimumCompatibleCoreVersion ||
+            clientAuthenticate.coreProtocolVersion > serverHello.coreProtocolVersion) {
+            throw new Error("Direct Runtime authentication negotiation does not match server hello");
+        }
+        const helloFields = withoutSignature(serverHello);
+        const authenticateFields = withoutSignature(clientAuthenticate);
+        const helloHash = sha256(encodeServerHelloCanonical(helloFields));
+        const authenticateHash = sha256(encodeClientAuthenticateCanonical(authenticateFields));
+        const clientPublicKey = createEd25519PublicKey(clientAuthenticate.clientPublicKey);
+        const clientProof = encodeClientAuthenticateProofPayload(channelBinding, helloHash, authenticateFields);
+        if (!verify(null, clientProof, clientPublicKey, Buffer.from(clientAuthenticate.signature, "base64url"))) {
+            throw new Error("Direct Runtime client proof is invalid");
+        }
+        signal.throwIfAborted();
+        const grant = clientAuthenticate.mode === "enroll"
+            ? this.access.redeemPairingClaim({
+                claimId: clientAuthenticate.claimId,
+                claimSecret: clientAuthenticate.claimSecret,
+                clientId: clientAuthenticate.clientId,
+                clientPublicKey: clientAuthenticate.clientPublicKey,
+            })
+            : this.access.resolveActiveGrant({
+                grantId: clientAuthenticate.grantId,
+                clientId: clientAuthenticate.clientId,
+                clientPublicKey: clientAuthenticate.clientPublicKey,
+            });
+        signal.throwIfAborted();
+        const acceptedFields = {
+            type: "server.accepted",
+            role,
+            daemonId: serverHello.daemonId,
+            daemonInstanceId: serverHello.daemonInstanceId,
+            bindingProtocolVersion: clientAuthenticate.bindingProtocolVersion,
+            coreProtocolVersion: clientAuthenticate.coreProtocolVersion,
+            channelId: randomUUID(),
+            grantId: grant.grantId,
+            clientId: grant.clientId,
+            authorities: ["daemon.full"],
+        };
+        const accepted = parseServerAccepted({
+            ...acceptedFields,
+            signature: this.identity.signDirectRuntimeServerAccepted(channelBinding, helloHash, authenticateHash, acceptedFields),
+        });
+        return {
+            peer: {
+                clientId: grant.clientId,
+                grantId: grant.grantId,
+                subject: {
+                    subjectId: `client:${grant.clientId}`,
+                    effectiveAuthorities: [...grant.authorities],
+                },
+            },
+            accepted,
+        };
+    }
+}
+function bindingProtocol(role) {
+    switch (role) {
+        case "control":
+            return DIRECT_RUNTIME_BINDING_PROTOCOL;
+        case "browser-surface":
+            return DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL;
+        case "browser-inspect":
+            return DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL;
+    }
+}
+function withoutSignature(value) {
+    const { signature: _signature, ...fields } = value;
+    return fields;
+}
+function sha256(value) {
+    return Uint8Array.from(createHash("sha256").update(value).digest());
+}
+function createEd25519PublicKey(encoded) {
+    const key = createPublicKey({
+        key: Buffer.from(encoded, "base64url"),
+        format: "der",
+        type: "spki",
+    });
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new Error("Direct Runtime client key must use Ed25519");
+    }
+    return key;
+}

package/dist/direct-runtime-config.d.ts

@@ -0,0 +1,20 @@
+export interface DirectRuntimeConfig {
+    bindHost: string;
+    /** Preferred port. The daemon replaces this with the actual bound port. */
+    port: number;
+    /** Present only in automatic mode. Candidates are tried after `port`. */
+    fallbackPorts?: readonly number[];
+    /** The preferred port came from advisory persisted state, so any bind failure may skip it. */
+    preferredPortIsPersistedFallback?: boolean;
+    /** Present only in automatic mode. Records the successfully bound port. */
+    recordListeningPort?: (port: number) => Promise<void>;
+}
+/**
+ * Resolve the daemon's always-available Direct Runtime listener.
+ *
+ * Normal operation has no certificate, advertised-route, or enablement
+ * configuration. The two RYNX_RUNTIME_* inputs are intentionally narrow
+ * deployment/test seams for overriding the socket bind only.
+ */
+export declare function loadDirectRuntimeConfig(env?: NodeJS.ProcessEnv): Promise<DirectRuntimeConfig>;
+export declare function directRuntimeFallbackPortFile(env?: NodeJS.ProcessEnv): string;

package/dist/direct-runtime-config.js

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+const DEFAULT_BIND_HOST = "0.0.0.0";
+const DEFAULT_PORT = 7443;
+const FALLBACK_PORT_FILE = "direct-runtime-port";
+/**
+ * Resolve the daemon's always-available Direct Runtime listener.
+ *
+ * Normal operation has no certificate, advertised-route, or enablement
+ * configuration. The two RYNX_RUNTIME_* inputs are intentionally narrow
+ * deployment/test seams for overriding the socket bind only.
+ */
+export async function loadDirectRuntimeConfig(env = process.env) {
+    const bindHost = parseBindHost(env.RYNX_RUNTIME_BIND_HOST);
+    const explicitPort = parseExplicitPort(env.RYNX_RUNTIME_PORT);
+    if (explicitPort !== undefined)
+        return { bindHost, port: explicitPort };
+    const persistedPort = await readPersistedFallbackPort(env);
+    return {
+        bindHost,
+        port: persistedPort ?? DEFAULT_PORT,
+        fallbackPorts: persistedPort === undefined
+            ? [0]
+            : [DEFAULT_PORT, 0],
+        ...(persistedPort === undefined
+            ? {}
+            : { preferredPortIsPersistedFallback: true }),
+        recordListeningPort: (port) => persistFallbackPort(port, env),
+    };
+}
+export function directRuntimeFallbackPortFile(env = process.env) {
+    return join(rynxHome(env), FALLBACK_PORT_FILE);
+}
+function parseBindHost(value) {
+    const host = value?.trim() || DEFAULT_BIND_HOST;
+    if (/\s|\//.test(host)) {
+        throw new Error("RYNX_RUNTIME_BIND_HOST is invalid");
+    }
+    return host;
+}
+function parseExplicitPort(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    if (!/^\d{1,5}$/.test(value)) {
+        throw new Error("RYNX_RUNTIME_PORT must be an integer from 1 to 65535");
+    }
+    const port = Number(value);
+    if (port < 1 || port > 65_535) {
+        throw new Error("RYNX_RUNTIME_PORT must be an integer from 1 to 65535");
+    }
+    return port;
+}
+async function readPersistedFallbackPort(env) {
+    let value;
+    try {
+        value = (await readFile(directRuntimeFallbackPortFile(env), "utf8")).trim();
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    if (!/^\d{1,5}$/.test(value))
+        return undefined;
+    const port = Number(value);
+    return port >= 1 && port <= 65_535 && port !== DEFAULT_PORT
+        ? port
+        : undefined;
+}
+async function persistFallbackPort(port, env) {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error("Direct Runtime listening port must be an integer from 1 to 65535");
+    }
+    const file = directRuntimeFallbackPortFile(env);
+    if (port === DEFAULT_PORT) {
+        await rm(file, { force: true });
+        return;
+    }
+    const directory = rynxHome(env);
+    const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`;
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        await writeFile(temporary, `${port}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function hasCode(error, code) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}