@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,317 @@
+import { mkdirSync } from "node:fs";
+import { chmod, chown, rm, stat } from "node:fs/promises";
+import net from "node:net";
+import { dirname } from "node:path";
+import { AGENT_METHODS, IPC_METHODS, IPC_PROTOCOL, IpcEvent, VERSION, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, parseWire, } from "../core/index.js";
+import { encodeLine, LineDecoder, LineTooLongError } from "./framing.js";
+import { IS_WINDOWS, MAX_SOCKET_PATH_BYTES } from "./paths.js";
+import { newPipeName, readPointer, writePointer } from "./pipes.js";
+import { RPC } from "./rpc.js";
+import { checkPrivateDir, ensurePrivateDir, secureCreated } from "./trust.js";
+const MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+const AGENT_TIER = new Set(AGENT_METHODS);
+/** Connection ids are process-wide: the daemon keys session bindings by them across both sockets. */
+let nextConnectionId = 1;
+/** Why the `agent` tier refuses a method it does not serve (spec §8.2, "Two sockets"). */
+function agentTierRefusal(method) {
+    return `${method} is not served on the agent socket; people use it through the messaging CLI or the /messaging TUI`;
+}
+/**
+ * Starts one socket of the daemon API. Each connection first gets the hello (`IpcHello`), then
+ * answers to its requests. The socket's directory and its parent (`run/` and `$MESSAGING_HOME`)
+ * must be private: real directories owned by this user that no group or other user can write
+ * (`forbidden` otherwise); a missing one is created 0700. The caller owns their modes beyond that, so
+ * a deployment can let a group search them (spec §8.2). Refuses to start when another server answers
+ * on the socket; removes a stale socket file otherwise. The socket is 0600, or 0660 to `group`.
+ *
+ * On Windows (spec §8.2, "Windows") it listens on a fresh named pipe and writes `socketPath` as the pointer
+ * file that names it (`pipes.ts`); the directories are private by ACL, and a missing one is created private.
+ * `group` is refused there: Node cannot give a pipe to a group.
+ */
+export async function createIpcServer(options) {
+    const path = options.socketPath;
+    if (options.tier !== "agent" && options.tier !== "admin")
+        throw new MessagingError("invalid_request", "an IPC server needs a tier: agent or admin");
+    if (options.group !== undefined && options.tier !== "agent" && options.authorize === undefined) {
+        throw new MessagingError("invalid_request", "only the agent socket may be shared with a group, unless every admin call needs a grant");
+    }
+    if (options.group !== undefined && IS_WINDOWS)
+        throw new MessagingError("invalid_request", "an agent socket shared with a group is not supported on Windows");
+    if (!IS_WINDOWS && Buffer.byteLength(path) > MAX_SOCKET_PATH_BYTES) {
+        throw new MessagingError("invalid_request", `socket path is longer than ${MAX_SOCKET_PATH_BYTES} bytes`);
+    }
+    const run = dirname(path);
+    const home = dirname(run);
+    const createdHome = mkdirSync(home, { recursive: true, mode: 0o700 }) !== undefined;
+    if (IS_WINDOWS && createdHome)
+        secureCreated(home, "the Messaging home directory");
+    checkPrivateDir(home, "the Messaging home directory", options.runParentOwners);
+    ensurePrivateDir(run, "the Messaging run directory");
+    await (IS_WINDOWS ? removeStalePointer(path) : removeStaleSocket(path));
+    // On Windows clients reach a pipe of a fresh name; `path` then becomes the pointer that names it.
+    const listenPath = IS_WINDOWS ? newPipeName(options.tier) : path;
+    const contexts = new Map();
+    // Every connection's first line (spec §8.2): which daemon this is, before any request.
+    const hello = {
+        jsonrpc: "2.0",
+        method: "hello",
+        params: { daemon: "messagingd", version: options.version ?? VERSION, protocol: IPC_PROTOCOL, pid: process.pid, ...(options.deployment ? { deployment: options.deployment } : {}) },
+    };
+    const server = net.createServer((socket) => {
+        const ctx = new Context(nextConnectionId++, options.tier, socket);
+        contexts.set(socket, ctx);
+        ctx.send(hello);
+        const decoder = new LineDecoder(LIMITS.ipcLineBytes);
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            let lines;
+            try {
+                lines = decoder.push(chunk);
+            }
+            catch (error) {
+                if (error instanceof LineTooLongError)
+                    ctx.send({ jsonrpc: "2.0", id: null, error: { code: RPC.invalidRequest, message: error.message } });
+                socket.destroy();
+                return;
+            }
+            for (const line of lines)
+                void dispatch(line, ctx);
+        });
+        socket.on("error", () => socket.destroy());
+        socket.on("close", () => {
+            contexts.delete(socket);
+            ctx.abort();
+            options.onDisconnect?.(ctx);
+        });
+    });
+    async function dispatch(line, ctx) {
+        let request;
+        try {
+            request = parseWire(line, { maxBytes: LIMITS.ipcLineBytes });
+        }
+        catch {
+            ctx.send({ jsonrpc: "2.0", id: null, error: { code: RPC.parseError, message: "parse error" } });
+            return;
+        }
+        if (!isRequest(request)) {
+            ctx.send({ jsonrpc: "2.0", id: null, error: { code: RPC.invalidRequest, message: "invalid request" } });
+            return;
+        }
+        const { id, method } = request;
+        if (id === undefined)
+            return; // client notifications are not part of the API
+        const spec = Object.hasOwn(IPC_METHODS, method) ? IPC_METHODS[method] : undefined;
+        const handler = options.handlers[method];
+        if (!spec || (!handler && method !== "events.subscribe")) {
+            ctx.send({ jsonrpc: "2.0", id, error: { code: RPC.methodNotFound, message: `method not found: ${method}` } });
+            return;
+        }
+        // The tier is checked before the params are read, so the agent socket tells nothing about the rest.
+        if (options.tier === "agent" && !AGENT_TIER.has(method)) {
+            ctx.send({ jsonrpc: "2.0", id, error: toRpcError(new MessagingError("forbidden", agentTierRefusal(method))) });
+            return;
+        }
+        // A grant is checked before the params are read too: a caller without one learns nothing about them.
+        let authority;
+        try {
+            authority = options.authorize?.({ method: method, params: request.params, grant: typeof request.grant === "string" ? request.grant : undefined, ctx });
+        }
+        catch (error) {
+            ctx.send({ jsonrpc: "2.0", id, error: toRpcError(error) });
+            if (!(error instanceof MessagingError))
+                options.onError?.(method, error);
+            return;
+        }
+        const parsed = spec.params.safeParse(request.params ?? {});
+        if (!parsed.success) {
+            ctx.send({ jsonrpc: "2.0", id, error: { code: RPC.invalidParams, message: describeIssues(parsed.error.issues) } });
+            return;
+        }
+        try {
+            const result = handler ? await handler(parsed.data, ctx, authority) : { ok: true };
+            // Subscriptions start only once the handler has accepted the keys.
+            if (method === "events.subscribe")
+                for (const key of parsed.data.keys)
+                    ctx.subscriptions.add(key);
+            const checked = spec.result.safeParse(result);
+            if (!checked.success)
+                throw new Error(`handler for ${method} returned an invalid result: ${describeIssues(checked.error.issues)}`);
+            if (!ctx.send({ jsonrpc: "2.0", id, result: checked.data })) {
+                ctx.send({ jsonrpc: "2.0", id, error: toRpcError(new MessagingError("too_large", `the ${method} result exceeds the IPC line limit`)) });
+            }
+        }
+        catch (error) {
+            ctx.send({ jsonrpc: "2.0", id, error: toRpcError(error) });
+            if (!(error instanceof MessagingError))
+                options.onError?.(method, error);
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // bind(2) creates the socket file with the umask's mode; keep it closed to everyone else until the
+        // chmod below, so a group that can search `run/` never reaches a socket meant for one user.
+        const umask = IS_WINDOWS ? undefined : process.umask(0o177);
+        try {
+            server.listen(listenPath, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        }
+        finally {
+            if (umask !== undefined)
+                process.umask(umask);
+        }
+    });
+    try {
+        if (IS_WINDOWS)
+            writePointer(path, { pipe: listenPath, pid: process.pid });
+        else {
+            if (options.group !== undefined)
+                await chown(path, process.geteuid?.() ?? -1, options.group);
+            await chmod(path, options.group === undefined ? 0o600 : 0o660);
+        }
+    }
+    catch (error) {
+        await new Promise((resolve) => server.close(() => resolve()));
+        await rm(path, { force: true });
+        if (options.group === undefined)
+            throw error;
+        throw new MessagingError("forbidden", `cannot give the agent socket to group ${options.group}: ${error.code ?? "error"}`);
+    }
+    return {
+        socketPath: path,
+        publish(event) {
+            const parsed = IpcEvent.parse(event);
+            for (const ctx of contexts.values()) {
+                if (ctx.subscriptions.size === 0)
+                    continue;
+                if ("key" in parsed && !ctx.subscriptions.has(parsed.key))
+                    continue;
+                if (!ctx.notify(parsed))
+                    options.onError?.("event", new MessagingError("too_large", `a ${parsed.type} event exceeds the IPC line limit`));
+            }
+        },
+        connections: () => contexts.size,
+        async close() {
+            for (const socket of contexts.keys())
+                socket.destroy();
+            await new Promise((resolve) => server.close(() => resolve()));
+            if (IS_WINDOWS) {
+                // Only this server's pointer: never one a later server wrote.
+                let ours = false;
+                try {
+                    ours = readPointer(path).pipe === listenPath;
+                }
+                catch {
+                    ours = false;
+                }
+                if (ours)
+                    await rm(path, { force: true });
+            }
+            else
+                await rm(path, { force: true });
+        },
+    };
+}
+class Context {
+    id;
+    tier;
+    socket;
+    subscriptions = new Set();
+    controller = new AbortController();
+    constructor(id, tier, socket) {
+        this.id = id;
+        this.tier = tier;
+        this.socket = socket;
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    abort() {
+        this.controller.abort();
+    }
+    /** Writes one line. Returns false, writing nothing, when the line would exceed `LIMITS.ipcLineBytes`: no peer could read it. */
+    send(message) {
+        const line = encodeLine(message);
+        if (Buffer.byteLength(line, "utf8") - 1 > LIMITS.ipcLineBytes)
+            return false;
+        if (this.socket.destroyed)
+            return true;
+        if (this.socket.writableLength > MAX_BUFFERED_BYTES) {
+            this.socket.destroy(); // a client that stops reading cannot grow daemon memory
+            return true;
+        }
+        this.socket.write(line);
+        return true;
+    }
+    notify(event) {
+        return this.send({ jsonrpc: "2.0", method: "event", params: event });
+    }
+}
+function isRequest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (v.jsonrpc === "2.0" &&
+        typeof v.method === "string" &&
+        (v.id === undefined || typeof v.id === "string" || typeof v.id === "number"));
+}
+function toRpcError(error) {
+    if (error instanceof MessagingError) {
+        return { code: MESSAGING_ERROR_RPC_CODE, message: error.message.slice(0, 500), data: { code: error.code } };
+    }
+    return { code: RPC.internalError, message: "internal error" };
+}
+/** Issue paths and messages only; never the offending values. */
+function describeIssues(issues) {
+    return `invalid params: ${issues
+        .slice(0, 5)
+        .map((i) => `${i.path.map(String).join(".") || "(root)"}: ${i.message}`)
+        .join("; ")}`.slice(0, 500);
+}
+/** Windows: refuses when the pipe an existing pointer names answers; removes the pointer otherwise. */
+async function removeStalePointer(path) {
+    const exists = await stat(path).then((s) => s, () => undefined);
+    if (!exists)
+        return;
+    if (!exists.isFile())
+        throw new MessagingError("invalid_request", "pipe file path exists and is not a file");
+    let pipe;
+    try {
+        pipe = readPointer(path).pipe;
+    }
+    catch {
+        pipe = undefined;
+    }
+    if (pipe !== undefined && (await answers(pipe)))
+        throw new MessagingError("invalid_request", "another daemon is already listening on this socket");
+    await rm(path, { force: true });
+}
+function answers(path) {
+    return new Promise((resolve) => {
+        const probe = net.connect(path);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once("error", () => resolve(false));
+    });
+}
+async function removeStaleSocket(path) {
+    const exists = await stat(path).then((s) => s, () => undefined);
+    if (!exists)
+        return;
+    if (!exists.isSocket())
+        throw new MessagingError("invalid_request", "socket path exists and is not a socket");
+    const live = await new Promise((resolve) => {
+        const probe = net.connect(path);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once("error", () => resolve(false));
+    });
+    if (live)
+        throw new MessagingError("invalid_request", "another daemon is already listening on this socket");
+    await rm(path, { force: true });
+}

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

@@ -0,0 +1,145 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { IPC_METHODS, MessagingError } from "../core/index.js";
+import { MessagingClient } from "./client.js";
+import { IS_WINDOWS, MAX_SOCKET_PATH_BYTES, socketPath as socketOf } from "./paths.js";
+import { createIpcServer } from "./server.js";
+import { newPipeName, readPointer, writePointer } from "./pipes.js";
+import { securePrivate } from "./windows-acl.js";
+/**
+ * `@messaging/ipc/testing`: helpers for tests only. Production code never imports this entry point.
+ *
+ * A fresh home whose `tier` socket path (`run/agent.sock` by default) is short enough for macOS
+ * (falls back to /tmp when the OS temp dir is too long). On Windows: a private (by ACL) home in the temp
+ * directory, and its `run\<tier>.pipe`.
+ */
+export function tempSocketPath(prefix = "mg-", tier = "agent") {
+    if (IS_WINDOWS) {
+        // No length limit for a pipe pointer; the home is made private by ACL, as messagingd makes its own.
+        const dir = mkdtempSync(join(tmpdir(), prefix));
+        securePrivate(dir, "a test home");
+        return { dir, socketPath: socketOf(dir, tier) };
+    }
+    for (const base of [tmpdir(), "/tmp"]) {
+        const dir = mkdtempSync(join(base, prefix));
+        const socketPath = socketOf(dir, tier);
+        if (Buffer.byteLength(socketOf(dir, "admin")) <= MAX_SOCKET_PATH_BYTES && Buffer.byteLength(socketPath) <= MAX_SOCKET_PATH_BYTES)
+            return { dir, socketPath };
+    }
+    throw new Error("no temp directory gives a short enough socket path");
+}
+/**
+ * Makes a bare `net.Server` listen where a client of `socketPath` will find it: on the socket itself, or on Windows
+ * on a fresh pipe that a pointer file at `socketPath` names, with `pid` (default this process's) as the pid the
+ * client will require in the hello. For impostors and other raw servers in tests.
+ */
+export async function listenAt(server, socketPath, { pid = process.pid } = {}) {
+    const tier = /admin\.(?:sock|pipe)$/.test(socketPath) ? "admin" : "agent";
+    const target = IS_WINDOWS ? newPipeName(tier) : socketPath;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(target, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    if (IS_WINDOWS)
+        writePointer(socketPath, { pipe: target, pid });
+}
+/** What `net.connect` takes to reach the endpoint at `socketPath`: the socket itself, or on Windows the pipe its pointer names. */
+export function rawEndpoint(socketPath) {
+    return IS_WINDOWS ? readPointer(socketPath).pipe : socketPath;
+}
+/** A deterministic ULID for test fixtures: `ulid(7)` is `01JC0000000000000000000007`. */
+export function ulid(n) {
+    return `01JC${String(n).padStart(22, "0")}`;
+}
+/** Polls `predicate` every 10 ms until it holds; throws after `timeoutMs`. */
+export async function until(predicate, timeoutMs = 3_000, what = "condition") {
+    const deadline = Date.now() + timeoutMs;
+    while (!predicate()) {
+        if (Date.now() > deadline)
+            throw new Error(`timed out waiting for ${what}`);
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+export async function recordingDaemon(options = {}) {
+    const owned = options.at === undefined;
+    const dir = options.at?.dir ?? tempSocketPath(options.prefix).dir;
+    const socketPath = socketOf(dir, "agent");
+    const adminSocketPath = socketOf(dir, "admin");
+    const handlers = { ...options.handlers };
+    const calls = [];
+    const convSubscribers = new Set();
+    const dispatch = {};
+    for (const method of Object.keys(IPC_METHODS)) {
+        dispatch[method] = async (params, ctx) => {
+            calls.push({ method, params: structuredClone(params) });
+            const handler = handlers[method];
+            if (!handler)
+                throw new MessagingError("forbidden", `fake daemon: no handler for ${method}`);
+            const result = await handler(params, ctx);
+            if (method === "conv.subscribe") {
+                convSubscribers.add(ctx);
+                ctx.signal.addEventListener("abort", () => convSubscribers.delete(ctx));
+            }
+            return result;
+        };
+    }
+    let servers;
+    const start = async () => {
+        if (servers)
+            return;
+        const version = options.version === undefined ? {} : { version: options.version };
+        const agent = await createIpcServer({ socketPath, tier: "agent", handlers: dispatch, ...version });
+        const admin = await createIpcServer({ socketPath: adminSocketPath, tier: "admin", handlers: dispatch, ...version }).catch(async (error) => {
+            await agent.close();
+            throw error;
+        });
+        servers = [agent, admin];
+    };
+    const stop = async () => {
+        const closing = servers ?? [];
+        servers = undefined;
+        for (const server of closing)
+            await server.close();
+    };
+    await start();
+    const callsTo = (method) => calls.filter((call) => call.method === method).map((call) => call.params);
+    return {
+        dir,
+        socketPath,
+        adminSocketPath,
+        calls,
+        methods: () => calls.map((call) => call.method),
+        callsTo,
+        last: (method) => callsTo(method).at(-1),
+        handle: (method, handler) => {
+            ;
+            handlers[method] = handler;
+        },
+        publish: (event) => {
+            for (const server of servers ?? [])
+                server.publish(event);
+        },
+        conv: (event) => {
+            for (const ctx of convSubscribers)
+                ctx.notify(event);
+        },
+        connect: (tier = "agent") => MessagingClient.connect({ socketPath: tier === "agent" ? socketPath : adminSocketPath, connectTimeoutMs: 500 }),
+        connections: () => (servers ?? []).reduce((sum, server) => sum + server.connections(), 0),
+        start,
+        stop,
+        restart: async (downMs = 50) => {
+            await stop();
+            await new Promise((resolve) => setTimeout(resolve, downMs));
+            await start();
+        },
+        close: async () => {
+            await stop();
+            if (owned)
+                rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}

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

@@ -0,0 +1,166 @@
+import { constants, lstatSync, mkdirSync, openSync } from "node:fs";
+import { MessagingError } from "../core/index.js";
+import { IS_WINDOWS } from "./paths.js";
+import { aclProblem, currentUserSid, readDacl, daclProblem, resolveSid, securePrivate, SID_OWNER_RIGHTS } from "./windows-acl.js";
+/**
+ * Directory trust for `$MESSAGING_HOME` and `run/` (spec §8.1, §8.2). A directory is private when it is a
+ * real directory (not a symlink), owned by a trusted user, and writable by nobody else (no group or
+ * other write bit). Whoever can write a directory on the socket's path can replace the socket and
+ * capture every client, so the server refuses to listen and clients refuse to connect unless both hold.
+ *
+ * The trusted owners are this process's effective user, plus, for a client, the daemon's own uid when
+ * one is configured (`MESSAGING_DAEMON_UID`): a deployment can run `messagingd` under its own user, with the
+ * engine in the group of `run/agent.sock` (spec §8.2, "Two sockets"). A group may read and search a
+ * directory, never write it.
+ *
+ * On Windows there is no mode and no cheap owner: a directory is private when it is a real directory whose
+ * ACL passes `daclProblem` with a pinned owner (`windows-acl.ts`); `owners` does not apply.
+ */
+export function checkPrivateDir(path, what, owners = selfOnly()) {
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new MessagingError("daemon_unavailable", `${what} does not exist`);
+        throw new MessagingError("forbidden", `cannot inspect ${what}`);
+    }
+    const problem = IS_WINDOWS ? windowsProblem(stats, path, "directory") : privacyProblem(stats, owners);
+    if (problem !== undefined)
+        throw new MessagingError("forbidden", `${what} is not private: it ${problem}`);
+}
+/**
+ * Creates `path` (mode 0700) when it is missing, then checks it as `checkPrivateDir` does. On Windows a
+ * directory it created that is not yet private (it inherited its parent's ACL) is made private
+ * (`securePrivate`); one that already existed is only checked.
+ */
+export function ensurePrivateDir(path, what) {
+    let created = false;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw new MessagingError("forbidden", `cannot create ${what}`);
+    }
+    if (IS_WINDOWS && created)
+        secureCreated(path, what);
+    checkPrivateDir(path, what);
+}
+/** Windows: makes a directory this process just created private, unless it already is (it inherited a private ACL). */
+export function secureCreated(path, what) {
+    if (aclProblem(path, { pinnedOwner: true }) !== undefined)
+        securePrivate(path, what);
+}
+/**
+ * Windows: the daemon's `chmod 0700` of a home directory (spec §8.1). A directory it just created is made
+ * private. An existing one is refused (`forbidden`) when it is a symlink, not a directory, or writable by anyone
+ * but this user, SYSTEM or Administrators; otherwise it is tightened to this user alone with its owner pinned
+ * (`securePrivate`), unless it already is.
+ */
+export function adoptPrivateDir(path, what, created) {
+    if (created) {
+        secureCreated(path, what);
+        return;
+    }
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch {
+        throw new MessagingError("forbidden", `cannot inspect ${what}`);
+    }
+    if (stats.isSymbolicLink())
+        throw new MessagingError("forbidden", `${what} is not private: it is a symbolic link`);
+    if (!stats.isDirectory())
+        throw new MessagingError("forbidden", `${what} is not private: it is not a directory`);
+    const self = currentUserSid();
+    const dacl = readDacl(path);
+    const problem = daclProblem(dacl, self, { pinnedOwner: false });
+    if (problem !== undefined)
+        throw new MessagingError("forbidden", `${what} is not private: it ${problem}`);
+    const exact = daclProblem(dacl, self, { pinnedOwner: true }) === undefined && (dacl?.aces ?? []).every((ace) => [self, SID_OWNER_RIGHTS].includes(resolveSid(ace.sid, self)));
+    if (!exact)
+        securePrivate(path, what);
+}
+/** Why `stats` is not a private directory owned by one of `owners` (default: this user), or undefined when it is. */
+export function privacyProblem(stats, owners = selfOnly()) {
+    if (stats.isSymbolicLink())
+        return "is a symbolic link";
+    if (!stats.isDirectory())
+        return "is not a directory";
+    if (owners.length > 0 && !owners.includes(stats.uid))
+        return "is owned by another user";
+    if ((stats.mode & 0o022) !== 0)
+        return "is writable by group or others";
+    return undefined;
+}
+/** Windows: why `path` (with its `lstat`) is not a private directory or file, or undefined when it is. */
+function windowsProblem(stats, path, kind) {
+    if (stats.isSymbolicLink())
+        return "is a symbolic link";
+    if (kind === "directory" ? !stats.isDirectory() : !stats.isFile())
+        return `is not a ${kind}`;
+    return aclProblem(path, { pinnedOwner: true });
+}
+/**
+ * The socket must be a socket owned by a trusted user (no symlink to someone else's). On Windows `path` is the
+ * pipe pointer file (`pipes.ts`): a regular file, not a symlink, private by `daclProblem` with a pinned owner.
+ */
+export function checkSocket(path, owners = selfOnly()) {
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new MessagingError("daemon_unavailable", "the Messaging daemon socket does not exist");
+        throw new MessagingError("forbidden", "cannot inspect the Messaging daemon socket");
+    }
+    if (IS_WINDOWS) {
+        const problem = windowsProblem(stats, path, "file");
+        if (problem !== undefined)
+            throw new MessagingError("forbidden", `the Messaging daemon's pipe file is not private: it ${problem}`);
+        return;
+    }
+    if (!stats.isSocket())
+        throw new MessagingError("forbidden", "the Messaging daemon socket path is not a socket");
+    if (owners.length > 0 && !owners.includes(stats.uid))
+        throw new MessagingError("forbidden", "the Messaging daemon socket is owned by another user");
+}
+/**
+ * The users a client trusts to own the daemon's directories and socket: itself, and `daemonUid` when
+ * given. Empty (no owner check) without `geteuid`.
+ */
+export function trustedOwners(daemonUid) {
+    const self = selfOnly();
+    if (self.length === 0)
+        return [];
+    return daemonUid === undefined || daemonUid === self[0] ? self : [...self, daemonUid];
+}
+function selfOnly() {
+    const euid = process.geteuid?.();
+    return euid === undefined ? [] : [euid];
+}
+/**
+ * `openSync(path, flags | O_NOFOLLOW, mode)`: refuses a symbolic link at `path` with `ELOOP`. Windows has no
+ * `O_NOFOLLOW`, so there the path is checked with `lstat` first (a symlink or junction is `ELOOP`), then opened.
+ * In a private directory only its owner could swap the path in between.
+ */
+export function openNoFollow(path, flags, mode) {
+    if (!IS_WINDOWS)
+        return openSync(path, flags | constants.O_NOFOLLOW, mode);
+    let link = false;
+    try {
+        link = lstatSync(path).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (link)
+        throw Object.assign(new Error(`ELOOP: a symbolic link, open '${path}'`), { code: "ELOOP" });
+    return openSync(path, flags, mode);
+}