@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/types/ipc/server.d.ts

@@ -0,0 +1,94 @@
+import type { z } from "zod";
+import { IpcEvent, type IpcMethod, type IpcMethods, type IpcResult } from "../core/index.js";
+import { type SocketTier } from "./paths.js";
+export interface ConnectionContext {
+    /** Unique across every server in this process, so a daemon with two sockets can key state by it. */
+    readonly id: number;
+    /** The tier of the socket this connection came in on. */
+    readonly tier: SocketTier;
+    /** Session keys this connection subscribed to with `events.subscribe`. */
+    readonly subscriptions: ReadonlySet<string>;
+    /** Aborted when the connection closes. */
+    readonly signal: AbortSignal;
+    /** Sends an event to this connection; false when it is too large to send. */
+    notify(event: IpcEvent): boolean;
+}
+/**
+ * What `authorize` decided for one call: `scope` names the grant that allowed it (`deployment: "jelly"`, spec
+ * §8.11), and `expiresAt` (ms) when that grant ends. Undefined when the call needed no grant.
+ */
+export interface CallAuthority {
+    readonly scope: "action" | "host";
+    readonly expiresAt: number;
+}
+/** One call as `authorize` sees it: before its params are parsed, with the request's `grant` member. */
+export interface AuthorizeCall {
+    readonly method: IpcMethod;
+    /** The params as received (absent: undefined). */
+    readonly params: unknown;
+    /** The request's top-level `grant` member, when it is a string. */
+    readonly grant: string | undefined;
+    readonly ctx: ConnectionContext;
+}
+export type Handler<M extends IpcMethod> = (params: z.output<IpcMethods[M]["params"]>, ctx: ConnectionContext, authority: CallAuthority | undefined) => Promise<IpcResult<M>> | IpcResult<M>;
+export type Handlers = {
+    [M in IpcMethod]?: Handler<M>;
+};
+export interface IpcServerOptions {
+    socketPath: string;
+    /**
+     * What this socket serves (spec §8.2, "Two sockets"). `agent`: only `AGENT_METHODS`; anything else is
+     * `forbidden` before its params are read. `admin`: every method.
+     */
+    tier: SocketTier;
+    /**
+     * A group that may connect: the socket is then 0660 and owned by this gid (the daemon's user must be
+     * in it). Without it the socket is 0600. On an `admin` socket only together with `authorize`
+     * (`deployment: "jelly"`, spec §8.11): a group may reach it only where every call there needs a grant.
+     */
+    group?: number;
+    /**
+     * Called for every call that passes the tier check, before its params are read. It throws a `MessagingError`
+     * to refuse the call (`grant_required`, `grant_invalid`), and returns what allowed it, which the handler gets.
+     */
+    authorize?: (call: AuthorizeCall) => CallAuthority | undefined;
+    /**
+     * Who may own the parent of the socket's directory (default: this user). A `run/` outside the home (`--run`,
+     * spec §8.11) may sit in a system directory that root owns: its parent must still be writable by nobody else.
+     */
+    runParentOwners?: readonly number[];
+    /** Named in the hello: `jelly` for a daemon under a Jelly host. */
+    deployment?: "jelly";
+    handlers: Handlers;
+    /** Called for unexpected handler failures. Never log params or results: they can hold message bodies. */
+    onError?: (method: string, error: unknown) => void;
+    /** Called after a connection closes (subscriptions are gone). */
+    onDisconnect?: (ctx: ConnectionContext) => void;
+    /** The release this server names in its hello; this build's `VERSION` unless a test says otherwise. */
+    version?: string;
+}
+export interface IpcServer {
+    /** Where clients find this endpoint: the socket, or on Windows the pipe pointer file. */
+    readonly socketPath: string;
+    /**
+     * Sends an event to every connection that called `events.subscribe` for its `key`; key-less events go
+     * to every such connection. So the daemon never publishes `chat` events here: it sends them itself,
+     * with `ctx.notify`, only to connections that called `chat.subscribe` (spec §6.8).
+     */
+    publish(event: IpcEvent): void;
+    connections(): number;
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function createIpcServer(options: IpcServerOptions): Promise<IpcServer>;

package/dist/types/ipc/testing.d.ts

@@ -0,0 +1,89 @@
+import type net from "node:net";
+import { type IpcEvent, type IpcMethod } from "../core/index.js";
+import { MessagingClient } from "./client.js";
+import { type SocketTier } from "./paths.js";
+import { type Handler, type Handlers } from "./server.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 declare function tempSocketPath(prefix?: string, tier?: SocketTier): {
+    dir: string;
+    socketPath: string;
+};
+/**
+ * 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 declare function listenAt(server: net.Server, socketPath: string, { pid }?: {
+    pid?: number;
+}): Promise<void>;
+/** What `net.connect` takes to reach the endpoint at `socketPath`: the socket itself, or on Windows the pipe its pointer names. */
+export declare function rawEndpoint(socketPath: string): string;
+/** A deterministic ULID for test fixtures: `ulid(7)` is `01JC0000000000000000000007`. */
+export declare function ulid(n: number): string;
+/** Polls `predicate` every 10 ms until it holds; throws after `timeoutMs`. */
+export declare function until(predicate: () => boolean, timeoutMs?: number, what?: string): Promise<void>;
+/** One call the fake received: the method and a copy of its parsed params, taken before its handler ran. */
+export interface Recorded {
+    method: IpcMethod;
+    params: Record<string, unknown>;
+}
+export type Params<M extends IpcMethod> = Parameters<Handler<M>>[0];
+export interface RecordingDaemonOptions {
+    /** Handlers by method; `handle` adds or replaces one later. Every other method is refused with `forbidden`. */
+    handlers?: Handlers;
+    /** Prefix of the temp home the fake creates (and removes on `close`). */
+    prefix?: string;
+    /** Use this home instead of a temp home of its own; `close` then leaves the directory alone. */
+    at?: {
+        dir: string;
+    };
+    /** The release its hello names (spec §8.2); this build's own unless a test plays another. */
+    version?: string;
+}
+/**
+ * A daemon stand-in on real Unix sockets, built on the IPC package's own server, so params are
+ * validated as messagingd validates them. Like messagingd it listens on both sockets of its home:
+ * `run/agent.sock` (the agent tier: `AGENT_METHODS` only) and `run/admin.sock` (every method). Every
+ * method of the contract is registered: each call the tier lets through is recorded once, then answered
+ * by its handler, or refused with `forbidden` ("fake daemon: no handler for <method>") when there is
+ * none. A fake that falls behind the contract fails loudly.
+ */
+export interface RecordingDaemon {
+    readonly dir: string;
+    /** The agent socket, `<dir>/run/agent.sock`. */
+    readonly socketPath: string;
+    /** The admin socket, `<dir>/run/admin.sock`. */
+    readonly adminSocketPath: string;
+    /** Every call, in order. */
+    readonly calls: Recorded[];
+    methods(): IpcMethod[];
+    callsTo<M extends IpcMethod>(method: M): Params<M>[];
+    last<M extends IpcMethod>(method: M): Params<M> | undefined;
+    /** Adds or replaces the handler for `method`, effective for the next call. */
+    handle<M extends IpcMethod>(method: M, handler: Handler<M>): void;
+    /** `IpcServer.publish`: to every connection that subscribed to the event's key (key-less: to all of them). */
+    publish(event: IpcEvent): void;
+    /** A `conv` event to the connections whose `conv.subscribe` succeeded, as messagingd sends it. */
+    conv(event: Extract<IpcEvent, {
+        type: "conv";
+    }>): void;
+    /** A client on the agent socket, or the `admin` one. */
+    connect(tier?: SocketTier): Promise<MessagingClient>;
+    /** Open connections on both sockets. */
+    connections(): number;
+    /** Listens (again) on the same socket; a no-op while listening. */
+    start(): Promise<void>;
+    /** Drops every connection and stops listening; the socket file goes away. */
+    stop(): Promise<void>;
+    /** `stop`, wait `downMs`, `start`: same path, same state. */
+    restart(downMs?: number): Promise<void>;
+    /** `stop`, and remove the temp home the fake created. */
+    close(): Promise<void>;
+}
+export declare function recordingDaemon(options?: RecordingDaemonOptions): Promise<RecordingDaemon>;

package/dist/types/ipc/trust.d.ts

@@ -0,0 +1,49 @@
+import { type Stats } from "node:fs";
+/**
+ * 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 declare function checkPrivateDir(path: string, what: string, owners?: readonly number[]): void;
+/**
+ * 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 declare function ensurePrivateDir(path: string, what: string): void;
+/** Windows: makes a directory this process just created private, unless it already is (it inherited a private ACL). */
+export declare function secureCreated(path: string, what: string): void;
+/**
+ * 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 declare function adoptPrivateDir(path: string, what: string, created: boolean): void;
+/** Why `stats` is not a private directory owned by one of `owners` (default: this user), or undefined when it is. */
+export declare function privacyProblem(stats: Stats, owners?: readonly number[]): string | undefined;
+/**
+ * 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 declare function checkSocket(path: string, owners?: readonly number[]): void;
+/**
+ * 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 declare function trustedOwners(daemonUid?: number): number[];
+/**
+ * `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 declare function openNoFollow(path: string, flags: number, mode?: number): number;

package/dist/types/ipc/windows-acl.d.ts

@@ -0,0 +1,56 @@
+export declare const SID_SYSTEM = "S-1-5-18";
+export declare const SID_ADMINISTRATORS = "S-1-5-32-544";
+export declare const SID_OWNER_RIGHTS = "S-1-3-4";
+/**
+ * Rights that let a principal change a file or directory, its entries, or who may: write data or add a file
+ * (0x2), append or add a subdirectory (0x4), write extended attributes (0x10), delete a child (0x40), write
+ * attributes (0x100), DELETE, WRITE_DAC, WRITE_OWNER, GENERIC_WRITE and GENERIC_ALL.
+ */
+export declare const WRITE_RIGHTS: number;
+export interface Ace {
+    /** SDDL ace type: `A` allow, `D` deny, `OA`, `XA`, … */
+    type: string;
+    flags: string[];
+    rights: number;
+    /** A full SID (`S-1-…`), or an alias this module does not map, as written. */
+    sid: string;
+}
+export interface Dacl {
+    /** `D:NO_ACCESS_CONTROL`: a NULL DACL. */
+    nullDacl: boolean;
+    /** `P`: inheritance from the parent is blocked. */
+    protected: boolean;
+    aces: Ace[];
+}
+/** The DACL part of an SDDL string, or undefined when it has none. Throws on text that is not SDDL. */
+export declare function parseSddlDacl(sddl: string): Dacl | undefined;
+/** `sid` as a full SID when it is a domain-relative alias of `self`'s domain; otherwise unchanged. */
+export declare function resolveSid(sid: string, self: string): string;
+/**
+ * Why `dacl` is not private to `self` (a SID), or undefined when it is (the rules in this module's comment).
+ * `pinnedOwner`: also require an OWNER RIGHTS entry that grants no write-class right.
+ */
+export declare function daclProblem(dacl: Dacl | undefined, self: string, { pinnedOwner }: {
+    pinnedOwner: boolean;
+}): string | undefined;
+/** This process's user SID (`whoami /user`), read once. */
+export declare function currentUserSid(): string;
+/**
+ * The DACL of `path`, read with `icacls /save` (SDDL; locale-independent). A path that is gone by the time icacls
+ * reads it is `daemon_unavailable`, not `forbidden`: a daemon that stops or restarts removes its pipe file between a
+ * client's `lstat` and this read, and that client has found no daemon, not an unsafe one.
+ */
+export declare function readDacl(path: string): Dacl | undefined;
+/** The SDDL line of an `icacls /save` file: the object's name, then its SDDL (UTF-16LE, with or without a BOM). */
+export declare function sddlLine(bytes: Buffer): string;
+/** Why `path`'s ACL is not private to this user (see `daclProblem`), or undefined. */
+export declare function aclProblem(path: string, options: {
+    pinnedOwner: boolean;
+}): string | undefined;
+/**
+ * Makes `path` (a directory) private to this user, as `chmod 0700` does on POSIX: inheritance from the parent
+ * removed, full control to this user and an OWNER RIGHTS entry that only reads the ACL, both inherited by
+ * everything created inside, and every other entry removed. Then reads the ACL back and checks it. Fails with
+ * `forbidden` when this user may not change the ACL.
+ */
+export declare function securePrivate(path: string, what: string): void;