@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/lib/modules/ipc/client.js

@@ -0,0 +1,289 @@
+import net from "node:net";
+import { dirname } from "node:path";
+import { ErrorCode, IPC_METHODS, IPC_PROTOCOL, IpcEvent, IpcHello, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, VERSION, parseWire, } from "../core/index.js";
+import { encodeLine, LineDecoder } from "./framing.js";
+import { configuredDaemonUid, IS_WINDOWS, messagingHome, socketPath as defaultSocketPath } from "./paths.js";
+import { readPointer } from "./pipes.js";
+import { RPC } from "./rpc.js";
+import { checkPrivateDir, checkSocket, trustedOwners } from "./trust.js";
+/**
+ * `daemon_mismatch`: the daemon on the socket is another release or IPC protocol, or did not say
+ * which (spec §8.2). `hello` is what it said, when it said anything this client can read.
+ */
+export class DaemonMismatchError extends MessagingError {
+    hello;
+    constructor(message, hello) {
+        super("daemon_mismatch", message);
+        this.hello = hello;
+        this.name = "DaemonMismatchError";
+    }
+}
+const REMEDY = "Stop it with `messaging daemon stop`, then start this version's daemon.";
+/** Another process's version text, printable and short, for a message. */
+function shown(version) {
+    return version.replace(/[^\x21-\x7e]/g, "?").slice(0, 64);
+}
+/** Non-Messaging JSON-RPC failure (schema, unknown method, internal). */
+export class IpcRpcError extends Error {
+    rpcCode;
+    constructor(rpcCode, message) {
+        super(message);
+        this.rpcCode = rpcCode;
+        this.name = "IpcRpcError";
+    }
+}
+/**
+ * One connection to the local daemon. It does not reconnect; watch `onClose` and connect again.
+ * Results are validated against the contract; malformed events are dropped.
+ */
+export class MessagingClient {
+    socket;
+    callTimeoutMs;
+    pending = new Map();
+    eventListeners = new Set();
+    closeListeners = new Set();
+    nextId = 1;
+    isClosed = false;
+    greeting;
+    /** The daemon's hello: the first line on the connection (spec §8.2). */
+    greeted;
+    daemonHello;
+    constructor(socket, callTimeoutMs) {
+        this.socket = socket;
+        this.callTimeoutMs = callTimeoutMs;
+        this.greeted = new Promise((resolve, reject) => (this.greeting = { resolve, reject }));
+        this.greeted.catch(() => undefined);
+        const decoder = new LineDecoder(LIMITS.ipcLineBytes);
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            let lines;
+            try {
+                lines = decoder.push(chunk);
+            }
+            catch (error) {
+                this.shutdown(error);
+                return;
+            }
+            for (const line of lines)
+                this.receive(line);
+        });
+        socket.on("error", (error) => this.shutdown(error));
+        socket.on("close", () => this.shutdown());
+    }
+    /**
+     * Connects to the daemon and reads its hello before anything else. A daemon of another release or
+     * IPC protocol, or one that does not say which within `helloTimeoutMs`, fails with
+     * `daemon_mismatch` (`DaemonMismatchError`, with the remedy in its message) and the connection is
+     * closed. The socket's directory must be private (a real directory owned by this
+     * user, or by the configured daemon uid, that no group or other user can write) and the socket owned
+     * by one of them; otherwise this fails with `forbidden`, because whoever can write that directory can
+     * stand in for the daemon.
+     *
+     * On Windows (spec §8.2, "Windows") `socketPath` is the pointer file that names the daemon's pipe. It and its
+     * directory must be private by ACL; the client connects to the pipe it names, and refuses (`forbidden`) a
+     * hello whose `pid` is not the pointer's.
+     */
+    static async connect(options = {}) {
+        const path = options.socketPath ?? defaultSocketPath(options.home ?? messagingHome(), options.tier ?? "agent");
+        const owners = trustedOwners(options.daemonUid ?? configuredDaemonUid());
+        let pointer;
+        try {
+            checkPrivateDir(dirname(path), "the Messaging daemon's socket directory", owners);
+            checkSocket(path, owners);
+            if (IS_WINDOWS)
+                pointer = readPointer(path);
+        }
+        catch (error) {
+            // A missing directory or socket is no daemon: the connect below reports `daemon_unavailable`.
+            if (!(error instanceof MessagingError) || error.code !== "daemon_unavailable")
+                throw error;
+        }
+        if (IS_WINDOWS && pointer === undefined)
+            throw new MessagingError("daemon_unavailable", "cannot reach the Messaging daemon (ENOENT)");
+        const timeout = options.connectTimeoutMs ?? 2_000;
+        const socket = await new Promise((resolve, reject) => {
+            const s = net.connect(pointer?.pipe ?? path);
+            const timer = setTimeout(() => {
+                s.destroy();
+                reject(new MessagingError("daemon_unavailable", "timed out connecting to the Messaging daemon"));
+            }, timeout);
+            s.once("connect", () => {
+                clearTimeout(timer);
+                resolve(s);
+            });
+            s.once("error", (error) => {
+                clearTimeout(timer);
+                reject(new MessagingError("daemon_unavailable", `cannot reach the Messaging daemon (${error.code ?? "error"})`, { cause: error }));
+            });
+        });
+        const client = new MessagingClient(socket, options.callTimeoutMs ?? 30_000);
+        const wait = options.helloTimeoutMs ?? Math.max(timeout, 5_000);
+        let timer;
+        try {
+            const hello = await Promise.race([
+                client.greeted,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new DaemonMismatchError(`the process on the Messaging daemon socket did not say which version it is within ${wait} ms: it is a messagingd from before this version, or it is stuck. ${REMEDY}`)), wait);
+                }),
+            ]);
+            // A pipe found through a stale pointer may be someone else's: only the daemon that wrote it is trusted.
+            if (pointer !== undefined && hello.pid !== pointer.pid) {
+                throw new MessagingError("forbidden", "the process on the Messaging daemon's pipe is not the daemon that published it");
+            }
+            const expected = options.version ?? VERSION;
+            if (hello.protocol !== IPC_PROTOCOL || hello.version !== expected) {
+                throw new DaemonMismatchError(`the Messaging daemon for this home is version ${shown(hello.version)} (IPC protocol ${hello.protocol}), and this client is version ${shown(expected)} (IPC protocol ${IPC_PROTOCOL}). ${REMEDY}`, hello);
+            }
+            client.daemonHello = hello;
+            return client;
+        }
+        catch (error) {
+            client.close();
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** What the daemon said when this connection opened: its release, IPC protocol and pid. */
+    get daemon() {
+        return this.daemonHello;
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    call(method, params, options = {}) {
+        if (this.isClosed)
+            return Promise.reject(new MessagingError("daemon_unavailable", "connection to the Messaging daemon is closed"));
+        if (options.signal?.aborted)
+            return Promise.reject(abortError(options.signal));
+        const id = this.nextId++;
+        const line = encodeLine({ jsonrpc: "2.0", id, method, params, ...(options.grant !== undefined ? { grant: options.grant } : {}) });
+        // The daemon closes a connection that sends an oversized line; refuse it here instead.
+        if (Buffer.byteLength(line, "utf8") - 1 > LIMITS.ipcLineBytes)
+            return Promise.reject(new MessagingError("too_large", `the ${method} request exceeds the IPC line limit`));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.settle(id, undefined, new MessagingError("daemon_unavailable", `${method} timed out`)), options.timeoutMs ?? this.callTimeoutMs);
+            const onAbort = () => this.settle(id, undefined, abortError(options.signal));
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            this.pending.set(id, {
+                method,
+                resolve: resolve,
+                reject,
+                cleanup: () => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", onAbort);
+                },
+            });
+            this.socket.write(line);
+        });
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    onClose(listener) {
+        this.closeListeners.add(listener);
+        return () => this.closeListeners.delete(listener);
+    }
+    close() {
+        this.socket.destroy();
+        this.shutdown();
+    }
+    receive(line) {
+        let message;
+        try {
+            const value = parseWire(line, { maxBytes: LIMITS.ipcLineBytes });
+            if (typeof value === "object" && value !== null && !Array.isArray(value))
+                message = value;
+        }
+        catch {
+            message = undefined;
+        }
+        if (this.greeting) {
+            // The first line must be the hello; anything else is not a daemon this client can talk to.
+            const greeting = this.greeting;
+            this.greeting = undefined;
+            const hello = message?.method === "hello" ? IpcHello.safeParse(message.params) : undefined;
+            if (hello?.success)
+                greeting.resolve(hello.data);
+            else
+                greeting.reject(new DaemonMismatchError(`the process on the Messaging daemon socket did not start with a hello this client can read: it is a messagingd of another version, or not a messagingd. ${REMEDY}`));
+            return;
+        }
+        if (!message)
+            return;
+        if (message.method === "event") {
+            const event = IpcEvent.safeParse(message.params);
+            if (!event.success)
+                return;
+            for (const listener of this.eventListeners) {
+                try {
+                    listener(event.data);
+                }
+                catch {
+                    // a listener failure must not break the connection
+                }
+            }
+            return;
+        }
+        if (typeof message.id !== "number")
+            return;
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        if (message.error !== undefined) {
+            this.settle(message.id, undefined, toError(message.error));
+            return;
+        }
+        const checked = IPC_METHODS[pending.method].result.safeParse(message.result);
+        if (!checked.success) {
+            this.settle(message.id, undefined, new MessagingError("internal", `daemon returned an invalid result for ${pending.method}`));
+            return;
+        }
+        this.settle(message.id, checked.data);
+    }
+    settle(id, value, error) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        pending.cleanup();
+        if (error)
+            pending.reject(error);
+        else
+            pending.resolve(value);
+    }
+    shutdown(error) {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.greeting?.reject(new MessagingError("daemon_unavailable", "the Messaging daemon closed the connection before it said hello"));
+        this.greeting = undefined;
+        for (const id of [...this.pending.keys()]) {
+            this.settle(id, undefined, new MessagingError("daemon_unavailable", "connection to the Messaging daemon closed"));
+        }
+        for (const listener of this.closeListeners) {
+            try {
+                listener(error);
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.eventListeners.clear();
+        this.closeListeners.clear();
+    }
+}
+function toError(raw) {
+    const e = (raw ?? {});
+    const message = typeof e.message === "string" ? e.message : "daemon error";
+    if (e.code === MESSAGING_ERROR_RPC_CODE) {
+        const code = ErrorCode.safeParse(e.data?.code);
+        return new MessagingError(code.success ? code.data : "internal", message);
+    }
+    return new IpcRpcError(typeof e.code === "number" ? e.code : RPC.internalError, message);
+}
+function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("aborted", "AbortError");
+}

package/dist/lib/modules/ipc/framing.js

@@ -0,0 +1,33 @@
+/** Splits a byte stream into newline-delimited lines, enforcing a per-line byte limit. */
+export class LineDecoder {
+    maxBytes;
+    pending = "";
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    /** Returns complete lines. Throws `LineTooLongError` once a line exceeds the limit. */
+    push(chunk) {
+        this.pending += chunk;
+        const parts = this.pending.split("\n");
+        this.pending = parts.pop() ?? "";
+        if (Buffer.byteLength(this.pending, "utf8") > this.maxBytes)
+            throw new LineTooLongError(this.maxBytes);
+        const lines = [];
+        for (const line of parts) {
+            if (Buffer.byteLength(line, "utf8") > this.maxBytes)
+                throw new LineTooLongError(this.maxBytes);
+            if (line.trim() !== "")
+                lines.push(line);
+        }
+        return lines;
+    }
+}
+export class LineTooLongError extends Error {
+    constructor(maxBytes) {
+        super(`line exceeds ${maxBytes} bytes`);
+        this.name = "LineTooLongError";
+    }
+}
+export function encodeLine(value) {
+    return `${JSON.stringify(value)}\n`;
+}

package/dist/lib/modules/ipc/index.js

@@ -0,0 +1,6 @@
+export { DaemonMismatchError, MessagingClient, IpcRpcError } from "./client.js";
+export { createIpcServer } from "./server.js";
+export { configuredDaemonUid, daemonEnv, IS_WINDOWS, messagingHome, socketPath } from "./paths.js";
+export { RPC } from "./rpc.js";
+export { adoptPrivateDir, openNoFollow, privacyProblem, trustedOwners } from "./trust.js";
+export { aclProblem } from "./windows-acl.js";

package/dist/lib/modules/ipc/paths.js

@@ -0,0 +1,102 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { MessagingError } from "../core/index.js";
+/** macOS limits sun_path to 104 bytes including the terminator. */
+export const MAX_SOCKET_PATH_BYTES = 103;
+/**
+ * Windows: the daemon's endpoints are named pipes found through pointer files (`pipes.ts`), its directories
+ * and files are private by ACL (`windows-acl.ts`), and there are no POSIX signals.
+ */
+export const IS_WINDOWS = process.platform === "win32";
+/** `$MESSAGING_HOME`, else `~/.messaging`. */
+export function messagingHome(env = process.env) {
+    const configured = env.MESSAGING_HOME;
+    return configured ? resolve(configured) : join(homedir(), ".messaging");
+}
+/**
+ * Where a client finds the `tier` endpoint of the daemon of `home`: the socket `run/<tier>.sock`, or on Windows
+ * the pointer file `run\<tier>.pipe` that names the tier's pipe (spec §8.2, "Windows").
+ */
+export function socketPath(home, tier) {
+    return join(home, "run", `${tier}.${IS_WINDOWS ? "pipe" : "sock"}`);
+}
+/**
+ * `MESSAGING_DAEMON_UID`: the uid a client also trusts to own the daemon's `run/` directory and socket,
+ * when `messagingd` runs as its own user (spec §8.2). Unset: only this process's own user. POSIX only: on
+ * Windows a set value is `invalid_request`.
+ */
+export function configuredDaemonUid(env = process.env, windows = IS_WINDOWS) {
+    const raw = env.MESSAGING_DAEMON_UID;
+    if (raw === undefined || raw === "")
+        return undefined;
+    // A daemon under its own user needs an endpoint shared with a group, which Node cannot make on Windows.
+    if (windows)
+        throw new MessagingError("invalid_request", "MESSAGING_DAEMON_UID is not supported on Windows: messagingd runs as the user of its clients there");
+    if (!/^\d{1,10}$/.test(raw) || Number(raw) > 0xffff_fffe)
+        throw new MessagingError("invalid_request", "MESSAGING_DAEMON_UID must be a numeric uid");
+    return Number(raw);
+}
+/**
+ * Environment variables a client passes through when it starts the long-lived daemon (`messaging daemon
+ * start`, the OpenCode plugin's autostart). Provider API keys, cloud credentials, tokens and
+ * NODE_OPTIONS, which could preload code into the daemon, stay behind.
+ */
+export const DAEMON_ENV = [
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TMPDIR",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "XDG_STATE_HOME",
+    "XDG_CACHE_HOME",
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+    "NODE_EXTRA_CA_CERTS",
+    "MESSAGING_LOG_LEVEL",
+    "MESSAGING_IDENTITY_STORE",
+];
+/**
+ * Also passed on Windows: the variables Windows programs need to run at all (`SystemRoot`: Winsock and the
+ * crypto provider fail without it), find the user's profile and temp directories, and run system tools.
+ */
+export const DAEMON_ENV_WINDOWS = [
+    "SystemRoot",
+    "SystemDrive",
+    "windir",
+    "ComSpec",
+    "PATHEXT",
+    "USERPROFILE",
+    "USERNAME",
+    "USERDOMAIN",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "ProgramData",
+    "TEMP",
+    "TMP",
+    "NUMBER_OF_PROCESSORS",
+    "PROCESSOR_ARCHITECTURE",
+];
+/** The daemon environment: the `DAEMON_ENV` part of `env` (and on Windows `DAEMON_ENV_WINDOWS`), plus `MESSAGING_HOME`. */
+export function daemonEnv(env, home, windows = IS_WINDOWS) {
+    const out = {};
+    for (const name of windows ? [...DAEMON_ENV, ...DAEMON_ENV_WINDOWS] : DAEMON_ENV) {
+        const value = env[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    out.MESSAGING_HOME = home;
+    return out;
+}

package/dist/lib/modules/ipc/pipes.js

@@ -0,0 +1,65 @@
+/**
+ * The daemon's endpoints on Windows (spec §8.2, "Windows"): a named pipe per tier, found through a pointer file
+ * in `run\` that only this user can write.
+ *
+ * Pipe names share one machine-wide namespace in which any user can create a pipe. A predictable name could be
+ * created by someone else before the daemon starts, and a client would then hand that process its session keys
+ * and messages. So every server picks a fresh name with 128 random bits, `\\.\pipe\messaging-<hex>-<tier>`, and
+ * publishes it, with its pid, in `run\<tier>.pipe`. The pointer file is the trust root, as `run/` is on POSIX:
+ * clients check its ACL and its directory's before they read it, and require the daemon's hello to name the
+ * pointer's pid.
+ */
+import { randomBytes } from "node:crypto";
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { MessagingError, parseWire } from "../core/index.js";
+/** The only pipe names a client connects to. */
+export const PIPE_NAME = /^\\\\\.\\pipe\\messaging-[0-9a-f]{32}-(?:agent|admin)$/;
+const POINTER_BYTES = 1_024;
+/** A fresh, unpredictable pipe name for one server of `tier`. */
+export function newPipeName(tier) {
+    return `\\\\.\\pipe\\messaging-${randomBytes(16).toString("hex")}-${tier}`;
+}
+/** Writes the pointer atomically: a temp file beside it (inheriting the directory's ACL), renamed over it. */
+export function writePointer(path, pointer) {
+    const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(pointer)}\n`, { flag: "wx" });
+        renameSync(temp, path);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Reads a pointer file: `daemon_unavailable` when it is missing, `forbidden` when it is not exactly
+ * `{pipe, pid}` with a pipe name of the shape `newPipeName` makes.
+ */
+export function readPointer(path) {
+    let text;
+    try {
+        const bytes = readFileSync(path);
+        if (bytes.length > POINTER_BYTES)
+            throw new MessagingError("forbidden", "the Messaging daemon's pipe file is too large");
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof MessagingError)
+            throw error;
+        if (error.code === "ENOENT")
+            throw new MessagingError("daemon_unavailable", "the Messaging daemon's pipe file does not exist");
+        throw new MessagingError("forbidden", "cannot read the Messaging daemon's pipe file");
+    }
+    let value;
+    try {
+        value = parseWire(text);
+    }
+    catch {
+        throw new MessagingError("forbidden", "the Messaging daemon's pipe file is not valid JSON");
+    }
+    const { pipe, pid, ...rest } = (typeof value === "object" && value !== null && !Array.isArray(value) ? value : {});
+    if (typeof pipe !== "string" || !PIPE_NAME.test(pipe) || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid < 1 || Object.keys(rest).length > 0) {
+        throw new MessagingError("forbidden", "the Messaging daemon's pipe file does not name a Messaging pipe");
+    }
+    return { pipe, pid };
+}

package/dist/lib/modules/ipc/rpc.js

@@ -0,0 +1,8 @@
+/** Standard JSON-RPC 2.0 error codes. Messaging errors use MESSAGING_ERROR_RPC_CODE from @messaging/core. */
+export const RPC = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};