@rome-os/node-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rome OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# Rome Node Core
+
+`@rome-os/node-core` provides JavaScript APIs for a shared caller daemon and an
+embedded computer host. It runs on Node.js 24 or later, including an Electron
+main process. The CLI is published separately as `@rome-os/node`.
+
+## Shared caller
+
+A Web Server and CLI using the same configuration directory and daemon port
+share one caller daemon. The daemon owns the communication credential, Gateway
+connection, and pending requests. Each client uses one local WebSocket for
+requests and event subscriptions. The client entry does not load the host executor.
+
+```ts
+import {
+  createNodeClient,
+  nodeConfigFromEnvironment,
+} from "@rome-os/node-core/client";
+
+const client = createNodeClient(nodeConfigFromEnvironment(process.env));
+const status = await client.getConnectionStatus();
+const devices = await client.listDevices();
+const connections = await client.getDevicesStatus();
+const info = await client.describe("device-id");
+const result = await client.run("device-id", "exec", {
+  command: "git",
+  args: ["status"],
+  cwd: "/workspace",
+});
+client.disconnect();
+```
+
+`getConnectionStatus()` returns `null` when no daemon runs. Otherwise it returns
+`{ pid, protocolVersion, connection }`. It does not start a daemon or open a
+Gateway connection. `connection` describes the caller connection to Gateway,
+not the online state of remote devices. `listDevices()` returns authorized
+devices without asserting that they are online.
+
+`getDevicesStatus()` checks device reachability through read-only `system.info`
+requests through an existing daemon and returns `{ connection, checkedAt, devices }`.
+It returns `null` when no daemon runs and never starts or restarts one. Each device has
+`id`, `name`, `platform`, and status `connected`, `not_connected`, `unknown`, or
+`revoked`. The daemon shares concurrent checks and caches snapshots for ten
+seconds. A timeout is unknown, not proof that a device is offline. This call
+opens the shared Gateway connection when there are active devices to check.
+
+Device operations start the daemon on demand. Only remote actions open its
+Gateway connection. The daemon starts from this package's own entry point and
+does not require an installed CLI. Concurrent launches elect one owner through
+the OS listener bind before writing discovery state or connecting to Gateway.
+
+`disconnect()` closes the local client handle. It does not stop the shared daemon,
+cancel submitted operations, or interrupt other clients. `startDaemon(config)`
+and `stopDaemon(config)` explicitly manage the shared service. An incompatible
+protocol requires an explicit stop before restart. Requests are never replayed
+after a lost response.
+
+Subscribe to caller connection changes:
+
+```ts
+const unsubscribe = await client.subscribe("connection", (event) => {
+  if (event.transport === "connected") {
+    updateConnection(event.daemon.connection);
+  } else {
+    clearConnection();
+  }
+});
+
+await unsubscribe();
+client.disconnect();
+```
+
+`updateConnection` and `clearConnection` are application callbacks. Subscription
+starts the daemon if needed and delivers a snapshot before resolving. It does
+not open a Gateway connection. Events describe the daemon's caller connection;
+they do not report remote device presence. A local connection loss delivers
+`{ transport: "disconnected", daemon: null, reason: "connection_lost" }`.
+
+While subscribed, the client reconnects with backoff and restores subscriptions
+with a fresh snapshot. It does not restart a stopped daemon or replay missed
+events. Incompatible protocols deliver reason `incompatible` and stop reconnection.
+Listener exceptions can be handled with `createNodeClient(config, { onListenerError })`.
+Unsubscribe removes one listener; other listeners and clients remain subscribed.
+Close the client with `disconnect()` when its owning application shuts down.
+
+Use `createNodeConfig({ directory, port? })` for an explicit location. Pass the
+same environment to `nodeConfigFromEnvironment()` as the CLI to honor
+`ROME_NODE_CONFIG_DIR`, `ROME_NODE_DAEMON_PORT`, and platform defaults.
+The library does not select an environment implicitly.
+
+## Caller authorization
+
+```ts
+import { authorizeServer } from "@rome-os/node-core/auth";
+import { nodeConfigFromEnvironment } from "@rome-os/node-core/client";
+
+await authorizeServer(cloudOrigin, instanceToken, nodeConfigFromEnvironment(process.env));
+```
+
+Authorization exchanges the Instance Token with Cloud and stores only the
+communication credential. It does not start the daemon. Existing credentials
+for the selected Cloud origin are reused. `configureCaller(origin, token, config)`
+accepts an issued communication credential instead. The optional fourth argument
+to `authorizeServer` receives retry notifications without terminal output.
+
+## Embedded host
+
+The host runs in the application process, independently of the caller daemon.
+The application supplies credential storage, authorization interaction, and an
+abort signal. It receives structured events instead of terminal output.
+
+```ts
+import {
+  connectHost,
+  createFileCredentialStore,
+  loginDevice,
+} from "@rome-os/node-core/host";
+
+const controller = new AbortController();
+const running = connectHost({
+  cloudUrl: "https://romeos.cc",
+  name: "My computer",
+  signal: controller.signal,
+  credentials: createFileCredentialStore("/private/app-data/credential.json"),
+  authorize: (origin, name, signal) =>
+    loginDevice(origin, name, signal, (url) => showAuthorizationUrl(url)),
+  onEvent: (event) => updateApplicationState(event),
+});
+
+// At application shutdown, abort and await the host connection's completion.
+controller.abort();
+await running;
+```
+
+`showAuthorizationUrl` and `updateApplicationState` are application callbacks.
+A custom credential store implements `load`, `save`, and `clear`. The built-in
+login adapter uses a temporary loopback callback listener. Applications can
+supply their own authorization function returning a device session.
+
+The host exposes `system.info` and `exec`. Programs run as the application's OS
+user. Connection loss terminates direct child processes on a best-effort basis.
+A local caller timeout does not cancel remote execution.
+
+See [the architecture and operating guide](../../docs/rome-node.md) for protocol,
+credential, and failure semantics.

package/bin/daemon.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/daemon-entry.js";

package/dist/actions.d.ts

@@ -0,0 +1,20 @@
+export interface ActionRequest {
+    type: "request";
+    action: string;
+    args: unknown;
+}
+export type ActionResponse = {
+    type: "response";
+    ok: true;
+    result: unknown;
+} | {
+    type: "response";
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function actionError(code: string, message: string): ActionResponse;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseResponse(value: unknown): ActionResponse | null;

package/dist/actions.js

@@ -0,0 +1,18 @@
+export function actionError(code, message) {
+    return { type: "response", ok: false, error: { code, message } };
+}
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function parseResponse(value) {
+    if (!isRecord(value) || value.type !== "response")
+        return null;
+    if (value.ok === true && Object.hasOwn(value, "result"))
+        return { type: "response", ok: true, result: value.result };
+    if (value.ok === false &&
+        isRecord(value.error) &&
+        typeof value.error.code === "string" &&
+        typeof value.error.message === "string")
+        return actionError(value.error.code, value.error.message);
+    return null;
+}

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+import { type NodeConfig } from "./local.js";
+export declare function configureCaller(origin: string, token: string, config: NodeConfig): Promise<void>;
+export declare function authorizeServer(origin: string, instanceToken: string | undefined, config: NodeConfig, onRetry?: () => void): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,76 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { isRecord } from "./actions.js";
+import { CloudError, cloudOrigin, gatewayConfig } from "./cloud.js";
+import { daemonStatus } from "./daemon-client.js";
+import { callerCredentialPath, readOptionalCallerCredential, CallerConfigurationError, } from "./local.js";
+import { writePrivateJson } from "./storage.js";
+const communicationToken = /^romedev_[A-Za-z0-9_-]{43}$/;
+class ServerAuthError extends Error {
+    retryable;
+    constructor(message, retryable = false) {
+        super(message);
+        this.retryable = retryable;
+    }
+}
+export async function configureCaller(origin, token, config) {
+    if (!communicationToken.test(token))
+        throw new Error("Invalid communication token.");
+    if (await daemonStatus(config))
+        throw new CallerConfigurationError("daemon_running", "Stop the caller daemon before changing credentials.");
+    await gatewayConfig(origin, token);
+    await writePrivateJson(callerCredentialPath(config), { cloudUrl: origin, token });
+}
+async function exchangeInstanceToken(origin, token) {
+    let response;
+    try {
+        response = await fetch(new URL("/api/instance/gateway-credential", origin), {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+            redirect: "error",
+            cache: "no-store",
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        throw new ServerAuthError("Could not reach Rome Cloud to authorize this server.", true);
+    }
+    if (!response.ok)
+        throw new ServerAuthError(`Rome Cloud rejected server authorization (HTTP ${response.status}).`, response.status === 429 || response.status >= 500);
+    const body = await response.json().catch(() => null);
+    if (!isRecord(body) ||
+        typeof body.deviceToken !== "string" ||
+        !communicationToken.test(body.deviceToken))
+        throw new ServerAuthError("Rome Cloud returned an invalid communication credential.");
+    return body.deviceToken;
+}
+export async function authorizeServer(origin, instanceToken, config, onRetry) {
+    const cloudUrl = cloudOrigin(origin);
+    const existing = await readOptionalCallerCredential(config);
+    if (existing) {
+        if (existing.cloudUrl !== cloudUrl)
+            throw new Error("Caller credentials belong to another Cloud origin. Configure auth manually.");
+        return;
+    }
+    const token = instanceToken?.trim();
+    if (!token || !/^romeinst_[A-Za-z0-9_-]+$/.test(token))
+        throw new CallerConfigurationError("instance_token_required", "Server authorization requires an Instance Token.");
+    if (await daemonStatus(config))
+        throw new CallerConfigurationError("daemon_running", "Stop the caller daemon before configuring credentials.");
+    let deviceToken;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (attempt > 0)
+            await delay(attempt === 1 ? 1000 : 5000);
+        try {
+            deviceToken ??= await exchangeInstanceToken(cloudUrl, token);
+            await configureCaller(cloudUrl, deviceToken, config);
+            return;
+        }
+        catch (error) {
+            const retryable = (error instanceof ServerAuthError && error.retryable) ||
+                (error instanceof CloudError && error.code === "cloud_unavailable");
+            if (!retryable || attempt === 2)
+                throw error;
+            onRetry?.();
+        }
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { type GatewayMessage, type OutboundEnvelope } from "./protocol.js";
+export interface ClientSocket {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code: number;
+    }) => void): void;
+    addEventListener(type: "error", listener: () => void): void;
+}
+export type ConnectionStatus = "connecting" | "online" | "retrying" | "revoked" | "superseded" | "stopped";
+export interface GatewayClientOptions {
+    gatewayUrl: string;
+    deviceToken: string;
+    createSocket(url: string, authorization: string): ClientSocket;
+    onMessage(message: GatewayMessage): void;
+    onStatus?(status: ConnectionStatus): void;
+    random?(): number;
+    beforeConnect?(): Promise<string | null>;
+}
+export declare function connectGateway(options: GatewayClientOptions): {
+    send(envelope: OutboundEnvelope): boolean;
+    stop(): void;
+};

package/dist/client.js

@@ -0,0 +1,130 @@
+import { parseGatewayUrl } from "./gateway-url.js";
+import { CLOSE, gatewayMessage, outboundEnvelope, } from "./protocol.js";
+export function connectGateway(options) {
+    let url = parseGatewayUrl(options.gatewayUrl);
+    if (!/^(?:romedev_|romemob_)[A-Za-z0-9_-]{43}$/.test(options.deviceToken))
+        throw new Error("Invalid device token format");
+    let stopped = false;
+    let socket = null;
+    let attempt = 0;
+    let timer;
+    let connectingTimer;
+    let stableTimer;
+    const status = (value) => options.onStatus?.(value);
+    const schedule = () => {
+        if (stopped || timer)
+            return;
+        status("retrying");
+        const delay = Math.min(60_000, 1000 * 2 ** Math.min(attempt++, 6));
+        timer = setTimeout(() => {
+            timer = undefined;
+            void open();
+        }, delay * (0.75 + (options.random ?? Math.random)() * 0.5));
+    };
+    const open = async () => {
+        if (stopped)
+            return;
+        status("connecting");
+        let current;
+        try {
+            if (options.beforeConnect) {
+                const next = await options.beforeConnect();
+                if (stopped)
+                    return;
+                if (next === null) {
+                    stopped = true;
+                    status("revoked");
+                    return;
+                }
+                url = parseGatewayUrl(next);
+            }
+            current = options.createSocket(url.toString(), `Bearer ${options.deviceToken}`);
+        }
+        catch {
+            schedule();
+            return;
+        }
+        socket = current;
+        let finished = false;
+        const finish = (code) => {
+            if (finished || socket !== current)
+                return;
+            finished = true;
+            clearTimeout(connectingTimer);
+            clearTimeout(stableTimer);
+            socket = null;
+            if (code === CLOSE.revoked || code === CLOSE.superseded) {
+                stopped = true;
+                status(code === CLOSE.revoked ? "revoked" : "superseded");
+            }
+            else
+                schedule();
+        };
+        connectingTimer = setTimeout(() => {
+            finish();
+            current.close();
+        }, 10_000);
+        current.addEventListener("open", () => {
+            if (stopped || socket !== current) {
+                current.close();
+                return;
+            }
+            clearTimeout(connectingTimer);
+            stableTimer = setTimeout(() => {
+                attempt = 0;
+            }, 30_000);
+            status("online");
+        });
+        current.addEventListener("message", ({ data }) => {
+            if (stopped || socket !== current || typeof data !== "string")
+                return;
+            let message;
+            try {
+                message = gatewayMessage(JSON.parse(data));
+            }
+            catch {
+                return;
+            }
+            if (message)
+                options.onMessage(message);
+        });
+        current.addEventListener("close", ({ code }) => finish(code));
+        current.addEventListener("error", () => {
+            finish();
+            current.close();
+        });
+    };
+    void open();
+    return {
+        send(envelope) {
+            if (stopped || !socket || socket.readyState !== 1 || !outboundEnvelope(envelope))
+                return false;
+            let text;
+            try {
+                text = JSON.stringify(envelope);
+                if (!outboundEnvelope(JSON.parse(text)))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            try {
+                socket.send(text);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+            clearTimeout(connectingTimer);
+            clearTimeout(stableTimer);
+            const previous = socket;
+            socket = null;
+            previous?.close(1000, "client stopped");
+            status("stopped");
+        },
+    };
+}

package/dist/cloud.d.ts

@@ -0,0 +1,7 @@
+export declare class CloudError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function cloudOrigin(value: string): string;
+export declare function cloudRequest(origin: string, path: string, token: string, method?: string): Promise<unknown>;
+export declare function gatewayConfig(origin: string, token: string): Promise<string>;

package/dist/cloud.js

@@ -0,0 +1,56 @@
+import { isRecord } from "./actions.js";
+import { parseGatewayUrl } from "./gateway-url.js";
+export class CloudError extends Error {
+    code;
+    constructor(code) {
+        super(code === "invalid_device_session"
+            ? "Device authorization is invalid."
+            : "Rome Cloud is unavailable. Retry later.");
+        this.code = code;
+    }
+}
+export function cloudOrigin(value) {
+    const url = new URL(value);
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/" ||
+        (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))))
+        throw new Error("Use an HTTPS Cloud origin. HTTP is allowed only on loopback.");
+    return url.origin;
+}
+export async function cloudRequest(origin, path, token, method = "GET") {
+    let response;
+    try {
+        response = await fetch(new URL(path, cloudOrigin(origin)), {
+            method,
+            headers: { Authorization: `Bearer ${token}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+            cache: "no-store",
+        });
+    }
+    catch {
+        throw new CloudError("cloud_unavailable");
+    }
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        if (response.status === 401 && isRecord(body) && body.error === "invalid_device_session")
+            throw new CloudError("invalid_device_session");
+        throw new CloudError("cloud_unavailable");
+    }
+    return body;
+}
+export async function gatewayConfig(origin, token) {
+    const body = await cloudRequest(origin, "/v1/gateway/config", token);
+    if (!isRecord(body) || typeof body.gatewayUrl !== "string")
+        throw new CloudError("invalid_response");
+    try {
+        return parseGatewayUrl(body.gatewayUrl).toString();
+    }
+    catch {
+        throw new CloudError("invalid_response");
+    }
+}

package/dist/connect.d.ts

@@ -0,0 +1,27 @@
+import type { DeviceSession } from "./login.js";
+import type { CredentialStore } from "./storage.js";
+export type HostCredential = DeviceSession & {
+    name: string;
+};
+export type HostEvent = {
+    type: "authorization_required";
+} | {
+    type: "retrying";
+} | {
+    type: "device";
+    name: string;
+    deviceId: string;
+} | {
+    type: "connection";
+    status: import("./client.js").ConnectionStatus;
+};
+export interface HostOptions {
+    cloudUrl: string;
+    name: string;
+    signal: AbortSignal;
+    credentials: CredentialStore<HostCredential>;
+    authorize(cloudUrl: string, name: string, signal: AbortSignal): Promise<DeviceSession>;
+    onEvent?(event: HostEvent): void;
+}
+export declare function connectHost(options: HostOptions): Promise<void>;
+export declare const defaultDeviceName: () => string;

package/dist/connect.js

@@ -0,0 +1,115 @@
+import { hostname } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import { isRecord } from "./actions.js";
+import { cloudOrigin, cloudRequest, CloudError, gatewayConfig } from "./cloud.js";
+import { connectGateway } from "./client.js";
+import { createNodeSocket } from "./socket.js";
+import { createExecutor } from "./executor.js";
+import { validId } from "./protocol.js";
+export async function connectHost(options) {
+    const { name, signal, credentials } = options;
+    if (signal.aborted)
+        return;
+    const cloudUrl = cloudOrigin(options.cloudUrl);
+    const stored = await credentials.load();
+    let session = isRecord(stored) &&
+        stored.cloudUrl === cloudUrl &&
+        typeof stored.token === "string" &&
+        /^romedev_[A-Za-z0-9_-]{43}$/.test(stored.token) &&
+        validId(stored.deviceId) &&
+        typeof stored.name === "string"
+        ? { cloudUrl, token: stored.token, deviceId: stored.deviceId, name: stored.name }
+        : null;
+    let gatewayUrl = "";
+    let attempt = 0;
+    while (!signal.aborted) {
+        if (!session) {
+            options.onEvent?.({ type: "authorization_required" });
+            session = { ...(await options.authorize(cloudUrl, name, signal)), name };
+            await credentials.save(session);
+        }
+        try {
+            gatewayUrl = await gatewayConfig(cloudUrl, session.token);
+            break;
+        }
+        catch (error) {
+            if (error instanceof CloudError && error.code === "invalid_device_session") {
+                await credentials.clear();
+                session = null;
+                continue;
+            }
+            options.onEvent?.({ type: "retrying" });
+            await delay(Math.min(60_000, 1000 * 2 ** Math.min(attempt++, 6)), undefined, {
+                signal,
+            }).catch(() => { });
+        }
+    }
+    if (signal.aborted || !session)
+        return;
+    const devices = await cloudRequest(cloudUrl, "/api/account/devices", session.token).catch(() => null);
+    if (isRecord(devices) && Array.isArray(devices.items)) {
+        const device = devices.items.find((item) => isRecord(item) && item.id === session?.deviceId);
+        if (isRecord(device) && typeof device.device_name === "string") {
+            session.name = device.device_name;
+            await credentials.save(session);
+        }
+    }
+    if (signal.aborted)
+        return;
+    const active = session;
+    options.onEvent?.({ type: "device", name: active.name, deviceId: active.deviceId });
+    await new Promise((resolve, reject) => {
+        const executor = createExecutor(active.name, (message) => connection.send(message), [
+            active.token,
+        ]);
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            signal.removeEventListener("abort", abort);
+            executor.disconnect();
+            connection.stop();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const abort = () => finish();
+        const connection = connectGateway({
+            gatewayUrl,
+            deviceToken: active.token,
+            createSocket: createNodeSocket,
+            beforeConnect: async () => {
+                try {
+                    return await gatewayConfig(cloudUrl, active.token);
+                }
+                catch (error) {
+                    if (error instanceof CloudError && error.code === "invalid_device_session")
+                        return null;
+                    throw error;
+                }
+            },
+            onMessage: (message) => {
+                if ("from" in message)
+                    void executor.receive(message);
+            },
+            onStatus: (status) => {
+                options.onEvent?.({ type: "connection", status });
+                if (status !== "online" && status !== "connecting")
+                    executor.disconnect();
+                if (status === "revoked" || status === "superseded") {
+                    queueMicrotask(() => finish(new Error(status === "revoked"
+                        ? "Authorization revoked. Explicit authorization is required."
+                        : "Another connection replaced this device. This process has stopped.")));
+                }
+            },
+        });
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+export const defaultDeviceName = () => hostname()
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .slice(0, 80) || "Computer";