@rome-os/node-core 0.1.0

package/dist/index.js

@@ -0,0 +1,4 @@
+export { connectGateway, } from "./client.js";
+export { MAX_MESSAGE_BYTES, byteLength, validId, } from "./protocol.js";
+export { CloudError, cloudOrigin, cloudRequest, gatewayConfig } from "./cloud.js";
+export { actionError, isRecord, parseResponse, } from "./actions.js";

package/dist/local.d.ts

@@ -0,0 +1,21 @@
+export interface NodeConfig {
+    directory: string;
+    port: number;
+}
+export declare function createNodeConfig(options: {
+    directory: string;
+    port?: number;
+}): NodeConfig;
+export declare function nodeConfigFromEnvironment(env: Record<string, string | undefined>): NodeConfig;
+export declare const callerCredentialPath: (config: NodeConfig) => string;
+export declare const daemonStatePath: (config: NodeConfig) => string;
+export interface CallerCredential {
+    cloudUrl: string;
+    token: string;
+}
+export declare class CallerConfigurationError extends Error {
+    readonly code: "not_configured" | "daemon_running" | "instance_token_required";
+    constructor(code: "not_configured" | "daemon_running" | "instance_token_required", message: string);
+}
+export declare function readOptionalCallerCredential(config: NodeConfig): Promise<CallerCredential | null>;
+export declare function readCallerCredential(config: NodeConfig): Promise<CallerCredential>;

package/dist/local.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { isRecord } from "./actions.js";
+import { cloudOrigin } from "./cloud.js";
+import { readPrivateJson } from "./storage.js";
+export function createNodeConfig(options) {
+    const directory = resolve(options.directory);
+    const port = options.port ??
+        20000 + (createHash("sha256").update(directory).digest().readUInt32BE(0) % 40000);
+    if (!Number.isInteger(port) || port < 1024 || port > 65535)
+        throw new Error("The daemon port must be between 1024 and 65535.");
+    return { directory, port };
+}
+export function nodeConfigFromEnvironment(env) {
+    return createNodeConfig({
+        directory: env.ROME_NODE_CONFIG_DIR ||
+            (process.platform === "win32"
+                ? join(env.LOCALAPPDATA || homedir(), "RomeNode")
+                : join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "rome-node")),
+        port: env.ROME_NODE_DAEMON_PORT === undefined ? undefined : Number(env.ROME_NODE_DAEMON_PORT),
+    });
+}
+export const callerCredentialPath = (config) => join(config.directory, "caller.json");
+export const daemonStatePath = (config) => join(config.directory, "daemon.json");
+export class CallerConfigurationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export async function readOptionalCallerCredential(config) {
+    const value = await readPrivateJson(callerCredentialPath(config));
+    if (!isRecord(value) ||
+        typeof value.cloudUrl !== "string" ||
+        typeof value.token !== "string" ||
+        !/^romedev_[A-Za-z0-9_-]{43}$/.test(value.token))
+        return null;
+    return { cloudUrl: cloudOrigin(value.cloudUrl), token: value.token };
+}
+export async function readCallerCredential(config) {
+    const credential = await readOptionalCallerCredential(config);
+    if (!credential)
+        throw new CallerConfigurationError("not_configured", "A caller communication credential is required.");
+    return credential;
+}

package/dist/login.d.ts

@@ -0,0 +1,6 @@
+export interface DeviceSession {
+    cloudUrl: string;
+    token: string;
+    deviceId: string;
+}
+export declare function loginDevice(cloudUrl: string, name: string, signal: AbortSignal, onAuthorizationRequired: (url: string) => void): Promise<DeviceSession>;

package/dist/login.js

@@ -0,0 +1,107 @@
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { platform } from "node:os";
+import { cloudOrigin } from "./cloud.js";
+import { validId } from "./protocol.js";
+export async function loginDevice(cloudUrl, name, signal, onAuthorizationRequired) {
+    const cloud = new URL(cloudOrigin(cloudUrl));
+    const verifier = randomBytes(32).toString("base64url");
+    const state = randomBytes(32).toString("base64url");
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error("Authorization canceled."));
+            return;
+        }
+        let redeeming = false;
+        const server = createServer(async (request, response) => {
+            const incoming = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method !== "GET" ||
+                incoming.pathname !== "/callback" ||
+                incoming.searchParams.get("state") !== state ||
+                incoming.searchParams.get("iss") !== cloud.origin ||
+                !incoming.searchParams.get("code") ||
+                redeeming) {
+                response.writeHead(400).end("Invalid authorization callback");
+                return;
+            }
+            redeeming = true;
+            try {
+                const result = await fetch(`${cloud.origin}/oauth2/token`, {
+                    method: "POST",
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]),
+                    redirect: "error",
+                    body: new URLSearchParams({
+                        grant_type: "authorization_code",
+                        client_id: "rome-computer",
+                        redirect_uri: redirectUri,
+                        code: incoming.searchParams.get("code"),
+                        code_verifier: verifier,
+                        platform: platform() === "darwin" ? "macos" : platform() === "win32" ? "windows" : "linux",
+                    }),
+                });
+                if (!result.ok)
+                    throw new Error("Token exchange rejected");
+                const body = (await result.json());
+                if (typeof body.access_token !== "string" ||
+                    !/^romedev_[A-Za-z0-9_-]{43}$/.test(body.access_token) ||
+                    !validId(body.device_id))
+                    throw new Error("Invalid token response");
+                response
+                    .writeHead(200, { "content-type": "text/plain", "cache-control": "no-store" })
+                    .end("Device authorized. Return to Rome Node.");
+                resolve({ cloudUrl: cloud.origin, token: body.access_token, deviceId: body.device_id });
+            }
+            catch {
+                response
+                    .writeHead(400)
+                    .end("Device authorization failed. Return to the application to retry.");
+                reject(new Error("Device authorization failed"));
+            }
+            finally {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", abort);
+                server.close();
+            }
+        });
+        let redirectUri;
+        const abort = () => {
+            clearTimeout(timer);
+            server.closeAllConnections();
+            server.close();
+            reject(new Error("Authorization canceled."));
+        };
+        const timer = setTimeout(() => {
+            server.close();
+            signal.removeEventListener("abort", abort);
+            reject(new Error("Login timed out"));
+        }, 5 * 60_000);
+        signal.addEventListener("abort", abort, { once: true });
+        server.on("error", () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            reject(new Error("Loopback listener failed"));
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string")
+                return;
+            redirectUri = `http://127.0.0.1:${address.port}/callback`;
+            const url = new URL("/oauth2/authorize", cloud);
+            url.search = new URLSearchParams({
+                response_type: "code",
+                client_id: "rome-computer",
+                redirect_uri: redirectUri,
+                code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+                code_challenge_method: "S256",
+                state,
+                display_name: name,
+            }).toString();
+            try {
+                onAuthorizationRequired(url.toString());
+            }
+            catch {
+                abort();
+            }
+        });
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,29 @@
+export declare const MAX_MESSAGE_BYTES: number;
+export declare const CLOSE: {
+    readonly revoked: 4001;
+    readonly superseded: 4002;
+    readonly outputLimit: 4003;
+    readonly invalid: 1008;
+    readonly tooLarge: 1009;
+};
+export interface OutboundEnvelope {
+    id: string;
+    to: string;
+    payload: unknown;
+}
+export interface InboundEnvelope {
+    id: string;
+    from: string;
+    payload: unknown;
+}
+interface RouteError {
+    id: string;
+    type: "error";
+    code: "target_unavailable" | "invalid_message" | "message_too_large";
+}
+export type GatewayMessage = InboundEnvelope | RouteError;
+export declare function validId(value: unknown): value is string;
+export declare function outboundEnvelope(value: unknown): OutboundEnvelope | null;
+export declare function gatewayMessage(value: unknown): GatewayMessage | null;
+export declare function byteLength(value: string): number;
+export {};

package/dist/protocol.js

@@ -0,0 +1,39 @@
+export const MAX_MESSAGE_BYTES = 32 * 1024 * 1024;
+export const CLOSE = {
+    revoked: 4001,
+    superseded: 4002,
+    outputLimit: 4003,
+    invalid: 1008,
+    tooLarge: 1009,
+};
+export function validId(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        !/[\u0000-\u0020\u007f]/.test(value));
+}
+export function outboundEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const item = value;
+    if (!validId(item.id) || !validId(item.to) || !Object.hasOwn(item, "payload"))
+        return null;
+    return { id: item.id, to: item.to, payload: item.payload };
+}
+export function gatewayMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const item = value;
+    if (!validId(item.id))
+        return null;
+    if (item.type === "error" &&
+        ["target_unavailable", "invalid_message", "message_too_large"].includes(String(item.code))) {
+        return item;
+    }
+    if (validId(item.from) && Object.hasOwn(item, "payload"))
+        return { id: item.id, from: item.from, payload: item.payload };
+    return null;
+}
+export function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}

package/dist/socket.d.ts

@@ -0,0 +1,2 @@
+import type { ClientSocket } from "./client.js";
+export declare function createNodeSocket(url: string, authorization: string): ClientSocket;

package/dist/socket.js

@@ -0,0 +1,25 @@
+import WebSocket from "ws";
+export function createNodeSocket(url, authorization) {
+    const socket = new WebSocket(url, {
+        headers: { Authorization: authorization },
+        handshakeTimeout: 10_000,
+        followRedirects: false,
+    });
+    let alive = true;
+    const heartbeat = setInterval(() => {
+        if (socket.readyState !== WebSocket.OPEN)
+            return;
+        if (!alive) {
+            socket.terminate();
+            return;
+        }
+        alive = false;
+        socket.ping();
+    }, 30_000);
+    heartbeat.unref();
+    socket.on("pong", () => {
+        alive = true;
+    });
+    socket.on("close", () => clearInterval(heartbeat));
+    return socket;
+}

package/dist/storage.d.ts

@@ -0,0 +1,8 @@
+export declare function readPrivateJson(path: string): Promise<unknown>;
+export declare function writePrivateJson(path: string, value: unknown): Promise<void>;
+export interface CredentialStore<T> {
+    load(): Promise<unknown>;
+    save(value: T): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function createFileCredentialStore<T>(path: string): CredentialStore<T>;

package/dist/storage.js

@@ -0,0 +1,55 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+export async function readPrivateJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError || error.code === "ENOENT")
+            return null;
+        throw new Error("Could not read the local credential file.");
+    }
+}
+export async function writePrivateJson(path, value) {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === "win32") {
+        const run = promisify(execFile);
+        const systemDirectory = join(process.env.SystemRoot ?? "C:\\Windows", "System32");
+        const { stdout } = await run(join(systemDirectory, "whoami.exe"), [
+            "/user",
+            "/fo",
+            "csv",
+            "/nh",
+        ]);
+        const sid = stdout.match(/S-1-\d+(?:-\d+)+/)?.[0];
+        if (!sid)
+            throw new Error("Could not determine the Windows account identity.");
+        await run(join(systemDirectory, "icacls.exe"), [
+            dir,
+            "/inheritance:r",
+            "/grant:r",
+            `*${sid}:(OI)(CI)F`,
+        ]);
+    }
+    else
+        await chmod(dir, 0o700);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export function createFileCredentialStore(path) {
+    return {
+        load: () => readPrivateJson(path),
+        save: (value) => writePrivateJson(path, value),
+        clear: () => rm(path, { force: true }),
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@rome-os/node-core",
+  "version": "0.1.0",
+  "description": "JavaScript APIs for Rome device hosts and shared caller daemons",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/daemon-client.d.ts",
+      "default": "./dist/daemon-client.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "default": "./dist/host.js"
+    },
+    "./daemon": {
+      "types": "./dist/daemon.d.ts",
+      "default": "./dist/daemon.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "default": "./dist/storage.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
+    "./socket": {
+      "types": "./dist/socket.d.ts",
+      "default": "./dist/socket.js"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@rstest/core": "^0.11.11",
+    "@types/node": "25.2.3",
+    "typescript": "^5.9.3",
+    "@types/ws": "^8.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rome-os/rome.git",
+    "directory": "packages/rome-node-core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && ../../scripts/test-env.sh rstest"
+  }
+}