@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/local/local-socket.js

@@ -0,0 +1,232 @@
+/**
+ * Local control socket of the gateway (ADR 0054 §6): `.zhin/gateway.sock` with mode 0600 in a
+ * directory only the current user can write (a named pipe on Windows). A second gateway on the
+ * same project is refused while the first answers; a socket left by a dead gateway is removed.
+ * Whoever can connect is the local owner (principal `'local'`).
+ */
+import { lstat, mkdir, chmod, rm, stat } from 'node:fs/promises';
+import { connect, createServer } from 'node:net';
+import { dirname } from 'node:path';
+import { isNamedPipe } from './paths.js';
+import { handshakeProof, LineDecoder, LOCAL_GATEWAY_RPC, MAX_LOCAL_LINE_BYTES, } from './protocol.js';
+export class LocalSocketError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'LocalSocketError';
+    }
+}
+const DEFAULT_MAX_CONNECTIONS = 32;
+const defaultUid = () => (typeof process.getuid === 'function' ? process.getuid() : undefined);
+/** Probes an existing endpoint: `live` when something accepts a connection. */
+export function probeLocalSocket(path, timeoutMs = 1_000) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        const timer = setTimeout(() => { socket.destroy(); resolve('live'); }, timeoutMs);
+        socket.once('connect', () => { clearTimeout(timer); socket.destroy(); resolve('live'); });
+        socket.once('error', (error) => {
+            clearTimeout(timer);
+            if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT' || error.code === 'ENOTSOCK')
+                resolve('dead');
+            else
+                reject(error);
+        });
+    });
+}
+/**
+ * Checks the socket's directory and any existing socket, removing a stale one. Throws
+ * {@link LocalSocketError} when another live gateway owns the path or ownership is wrong.
+ */
+export async function prepareLocalSocketPath(path, options = {}) {
+    const probe = () => probeLocalSocket(path, options.probeTimeoutMs);
+    if (isNamedPipe(path)) {
+        if (await probe() === 'live')
+            throw new LocalSocketError('in_use', `另一个网关正在使用 ${path}`);
+        return { removedStale: false };
+    }
+    const uid = (options.uid ?? defaultUid)();
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const dir = await lstat(directory);
+    if (!dir.isDirectory() || dir.isSymbolicLink())
+        throw new LocalSocketError('insecure_dir', `${directory} 不是目录`);
+    const sticky = (dir.mode & 0o1000) !== 0;
+    if (!sticky) {
+        if (uid !== undefined && dir.uid !== uid) {
+            throw new LocalSocketError('insecure_dir', `${directory} 属于其他用户（uid ${dir.uid}），拒绝在其中创建控制套接字`);
+        }
+        if ((dir.mode & 0o022) !== 0) {
+            throw new LocalSocketError('insecure_dir', `${directory} 可被其他用户写入（mode ${(dir.mode & 0o777).toString(8)}）；请执行 chmod go-w ${directory}`);
+        }
+    }
+    let existing;
+    try {
+        existing = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { removedStale: false };
+        throw error;
+    }
+    if (!existing.isSocket())
+        throw new LocalSocketError('not_socket', `${path} 已存在且不是套接字，拒绝覆盖`);
+    if (uid !== undefined && existing.uid !== uid) {
+        throw new LocalSocketError('not_owner', `${path} 属于其他用户（uid ${existing.uid}）；请以启动网关的用户运行`);
+    }
+    if (await probe() === 'live')
+        throw new LocalSocketError('in_use', `另一个网关正在使用 ${path}`);
+    await rm(path, { force: true });
+    return { removedStale: true };
+}
+/** The listening control server. */
+export class LocalControlServer {
+    path;
+    #server;
+    #sockets = new Set();
+    #handler;
+    #handshakeKey;
+    #inode;
+    #closed;
+    constructor(path, server, handler, handshakeKey) {
+        this.path = path;
+        this.#server = server;
+        this.#handler = handler;
+        this.#handshakeKey = handshakeKey;
+    }
+    /** Validates the path, removes a stale socket, then listens with mode 0600. */
+    static async open(options) {
+        await prepareLocalSocketPath(options.path, options);
+        await options.beforeListen?.();
+        const server = createServer();
+        server.maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+        const control = new LocalControlServer(options.path, server, options.handler, options.handshakeKey);
+        server.on('connection', (socket) => { control.#accept(socket); });
+        await control.#listen(options);
+        return control;
+    }
+    setHandler(handler) { this.#handler = handler; }
+    /** Stops accepting, drops connections and removes the socket file it created. */
+    close() {
+        this.#closed ??= (async () => {
+            for (const socket of this.#sockets)
+                socket.destroy();
+            await new Promise((resolve) => { this.#server.close(() => resolve()); });
+            if (isNamedPipe(this.path) || this.#inode === undefined)
+                return;
+            try {
+                // Only remove the file this server bound (a successor may have replaced it).
+                if ((await lstat(this.path)).ino === this.#inode)
+                    await rm(this.path, { force: true });
+            }
+            catch { /* already gone */ }
+        })();
+        return this.#closed;
+    }
+    async #listen(options) {
+        const pipe = isNamedPipe(this.path);
+        let previousMask;
+        // The bind happens synchronously inside listen(): the socket is created 0600.
+        if (!pipe) {
+            try {
+                previousMask = process.umask(0o177);
+            }
+            catch { /* workers cannot set umask */ }
+        }
+        try {
+            await new Promise((resolve, reject) => {
+                const onError = (error) => { reject(error); };
+                this.#server.once('error', onError);
+                try {
+                    this.#server.listen(this.path, () => { this.#server.off('error', onError); resolve(); });
+                }
+                finally {
+                    if (previousMask !== undefined) {
+                        process.umask(previousMask);
+                        previousMask = undefined;
+                    }
+                }
+            });
+        }
+        finally {
+            if (previousMask !== undefined)
+                process.umask(previousMask);
+        }
+        if (pipe)
+            return;
+        await chmod(this.path, 0o600);
+        const bound = await stat(this.path);
+        if ((bound.mode & 0o077) !== 0) {
+            await this.close();
+            throw new LocalSocketError('insecure_socket', `无法把 ${this.path} 限制为仅当前用户可访问`);
+        }
+        this.#inode = bound.ino;
+    }
+    #accept(socket) {
+        this.#sockets.add(socket);
+        socket.setEncoding('utf8');
+        const decoder = new LineDecoder();
+        const write = (line) => {
+            if (socket.destroyed || !socket.writable)
+                return;
+            let text = JSON.stringify(line);
+            // The peer refuses longer lines (UTF-8 bytes): answer with an error instead of breaking the connection.
+            if (Buffer.byteLength(text) > MAX_LOCAL_LINE_BYTES) {
+                if ('event' in line)
+                    return;
+                text = JSON.stringify({ id: line.id, ok: false, error: { code: 'unavailable', message: '回复超过本地套接字上限（1 MiB）；改用 HTTP 请求', status: 502 } });
+            }
+            socket.write(`${text}\n`);
+        };
+        socket.on('data', (chunk) => {
+            let lines;
+            try {
+                lines = decoder.push(chunk);
+            }
+            catch {
+                write({ id: 0, ok: false, error: { code: 'invalid_input', message: '请求过长', status: 400 } });
+                socket.end();
+                return;
+            }
+            for (const line of lines)
+                void this.#handle(line, write);
+        });
+        socket.on('error', () => { socket.destroy(); });
+        socket.on('close', () => { this.#sockets.delete(socket); });
+    }
+    async #handle(line, write) {
+        let request;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== 'object' || typeof parsed.type !== 'string'
+                || (typeof parsed.id !== 'number' && typeof parsed.id !== 'string'))
+                throw new Error('shape');
+            request = parsed;
+        }
+        catch {
+            write({ id: 0, ok: false, error: { code: 'invalid_input', message: '请求不是有效的 JSON 行', status: 400 } });
+            return;
+        }
+        if (request.type === LOCAL_GATEWAY_RPC.HELLO) {
+            const nonce = request.data?.nonce;
+            if (typeof nonce !== 'string' || nonce.length === 0 || nonce.length > 256) {
+                write({ id: request.id, ok: false, error: { code: 'invalid_input', message: 'nonce 必须是非空字符串', status: 400 } });
+                return;
+            }
+            write({ id: request.id, ok: true, data: { proof: this.#handshakeKey ? handshakeProof(this.#handshakeKey, nonce) : null } });
+            return;
+        }
+        const handler = this.#handler;
+        if (!handler) {
+            write({ id: request.id, ok: false, error: { code: 'unavailable', message: '网关正在启动', status: 503 } });
+            return;
+        }
+        try {
+            const result = await handler(request, (event) => { write({ id: request.id, event }); });
+            write({ id: request.id, ...result });
+        }
+        catch {
+            write({ id: request.id, ok: false, error: { code: 'internal', message: '网关内部错误', status: 500 } });
+        }
+    }
+}

package/lib/local/paths.d.ts

@@ -0,0 +1,34 @@
+export declare const GATEWAY_STATE_DIR = ".zhin";
+export declare const GATEWAY_SOCKET_FILE = "gateway.sock";
+export declare const GATEWAY_INFO_FILE = "gateway.json";
+export declare const GATEWAY_LOG_FILE = "gateway.log";
+/** `<root>/.zhin`. */
+export declare function gatewayStateDir(root: string): string;
+/** `<root>/.zhin/gateway.json`. */
+export declare function gatewayInfoFile(root: string): string;
+/** `<root>/.zhin/logs/gateway.log`: the background gateway's own output. */
+export declare function gatewayLogFile(root: string): string;
+/** Stable short hash of a project root; Windows paths are case-insensitive. */
+export declare function projectRootHash(root: string, platform?: NodeJS.Platform): string;
+/**
+ * `\\.\pipe\zhin-gateway-<hash of the project root>[-<nonce>]`. A running gateway adds a fresh
+ * random `nonce` per start: Node cannot set an owner or DACL on a named pipe, so the name keeps
+ * another local account from creating the pipe ahead of the gateway; only the gateway's state
+ * file (`.zhin/gateway.json`) records it, and clients also check the handshake proof keyed by
+ * that file ({@link LocalGatewayInfo.handshakeKey}).
+ */
+export declare function windowsPipeName(root: string, nonce?: string): string;
+export interface GatewaySocketPathOptions {
+    readonly platform?: NodeJS.Platform;
+    /** Windows: random pipe-name component of a running gateway (see {@link windowsPipeName}). */
+    readonly nonce?: string;
+    /** Fallback directory for roots too deep for a Unix socket path. Default `os.tmpdir()`. */
+    readonly tmpdir?: string;
+}
+/**
+ * The local control endpoint of a project. Unix: `<root>/.zhin/gateway.sock`, or
+ * `<tmpdir>/zhin-gateway-<hash>.sock` when that path would not fit `sun_path`.
+ */
+export declare function gatewaySocketPath(root: string, options?: GatewaySocketPathOptions): string;
+/** Whether an endpoint is a Windows named pipe (no file to stat, chmod or unlink). */
+export declare function isNamedPipe(path: string): boolean;

package/lib/local/paths.js

@@ -0,0 +1,58 @@
+/**
+ * Where a project's gateway keeps its local control endpoint and state (ADR 0054 §6):
+ * `.zhin/gateway.sock` (a named pipe `\\.\pipe\zhin-gateway-<hash>` on Windows) and
+ * `.zhin/gateway.json`.
+ */
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join, resolve, win32 } from 'node:path';
+export const GATEWAY_STATE_DIR = '.zhin';
+export const GATEWAY_SOCKET_FILE = 'gateway.sock';
+export const GATEWAY_INFO_FILE = 'gateway.json';
+export const GATEWAY_LOG_FILE = 'gateway.log';
+/** sockaddr_un.sun_path is 104 (macOS) / 108 (Linux) bytes including the terminator. */
+const MAX_UNIX_SOCKET_PATH_BYTES = 100;
+/** `<root>/.zhin`. */
+export function gatewayStateDir(root) {
+    return join(resolve(root), GATEWAY_STATE_DIR);
+}
+/** `<root>/.zhin/gateway.json`. */
+export function gatewayInfoFile(root) {
+    return join(gatewayStateDir(root), GATEWAY_INFO_FILE);
+}
+/** `<root>/.zhin/logs/gateway.log`: the background gateway's own output. */
+export function gatewayLogFile(root) {
+    return join(gatewayStateDir(root), 'logs', GATEWAY_LOG_FILE);
+}
+/** Stable short hash of a project root; Windows paths are case-insensitive. */
+export function projectRootHash(root, platform = process.platform) {
+    const normalized = platform === 'win32' ? win32.resolve(root).toLowerCase() : resolve(root);
+    return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+/**
+ * `\\.\pipe\zhin-gateway-<hash of the project root>[-<nonce>]`. A running gateway adds a fresh
+ * random `nonce` per start: Node cannot set an owner or DACL on a named pipe, so the name keeps
+ * another local account from creating the pipe ahead of the gateway; only the gateway's state
+ * file (`.zhin/gateway.json`) records it, and clients also check the handshake proof keyed by
+ * that file ({@link LocalGatewayInfo.handshakeKey}).
+ */
+export function windowsPipeName(root, nonce) {
+    return `\\\\.\\pipe\\zhin-gateway-${projectRootHash(root, 'win32')}${nonce ? `-${nonce}` : ''}`;
+}
+/**
+ * The local control endpoint of a project. Unix: `<root>/.zhin/gateway.sock`, or
+ * `<tmpdir>/zhin-gateway-<hash>.sock` when that path would not fit `sun_path`.
+ */
+export function gatewaySocketPath(root, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32')
+        return windowsPipeName(root, options.nonce);
+    const preferred = join(gatewayStateDir(root), GATEWAY_SOCKET_FILE);
+    if (Buffer.byteLength(preferred) <= MAX_UNIX_SOCKET_PATH_BYTES)
+        return preferred;
+    return join(options.tmpdir ?? tmpdir(), `zhin-gateway-${projectRootHash(root, platform)}.sock`);
+}
+/** Whether an endpoint is a Windows named pipe (no file to stat, chmod or unlink). */
+export function isNamedPipe(path) {
+    return path.startsWith('\\\\.\\pipe\\') || path.startsWith('\\\\?\\pipe\\');
+}

package/lib/local/protocol.d.ts

@@ -0,0 +1,140 @@
+import type { GatewayInstanceStatus, GatewayPackageEvent, GatewayRpcErrorCode, GatewayRpcErrorDetails } from '@zhin.js/console-protocol';
+/** Socket-only RPC: not reachable over HTTP. */
+export declare const LOCAL_GATEWAY_RPC: Readonly<{
+    /**
+     * `{ nonce }` → `{ proof }`: HMAC-SHA256 of `nonce` under the run's handshake key (recorded only
+     * in the 0600 `.zhin/gateway.json`). The CLI sends it first and refuses an endpoint that cannot
+     * prove it is this project's gateway (a squatted Windows named pipe). Answered before any other
+     * request, also while the gateway is still starting.
+     */
+    readonly HELLO: "gateway.hello";
+    /** Gateway process info and instance status. */
+    readonly INFO: "gateway.info";
+    /** Stops the instance, then the gateway. */
+    readonly SHUTDOWN: "gateway.shutdown";
+    /**
+     * `zhin console init` beside a running gateway (ADR 0049 §7): the gateway's own
+     * `ConsoleSetupService` answers, so a database switch is applied live (reconnect + instance
+     * restart) and the owner state changes at once.
+     */
+    readonly CONSOLE_SETUP_STATUS: "gateway.console.setup.status";
+    readonly CONSOLE_SETUP_DRIVERS: "gateway.console.setup.drivers";
+    /** `{ dialect, connection }` → the probe result. */
+    readonly CONSOLE_SETUP_DATABASE_TEST: "gateway.console.setup.database.test";
+    /** `{ dialect, connection }`: writes the config, reconnects the gateway, restarts the instance. */
+    readonly CONSOLE_SETUP_DATABASE: "gateway.console.setup.database";
+    /** `{ username, password, displayName? }`: the first owner. */
+    readonly CONSOLE_SETUP_OWNER: "gateway.console.setup.owner";
+    /** `zhin console user …` beside a running gateway: the gateway's `ConsoleIamService` answers. */
+    readonly CONSOLE_USER_LIST: "gateway.console.user.list";
+    /** `{ username, password, displayName?, role }`. */
+    readonly CONSOLE_USER_CREATE: "gateway.console.user.create";
+    /** `{ username, password }`: resets the password (revokes the user's sessions). */
+    readonly CONSOLE_USER_PASSWD: "gateway.console.user.passwd";
+    /** `{ username, disabled }`. */
+    readonly CONSOLE_USER_DISABLE: "gateway.console.user.disable";
+    /**
+     * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
+     * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no
+     * Console token (ADR 0054 §6). Answered like the HTTP route ({@link LocalGatewayHttpResponse}).
+     */
+    readonly HTTP_REQUEST: "gateway.http.request";
+}>;
+export type LocalGatewayHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface LocalGatewayHttpRequest {
+    readonly method: LocalGatewayHttpMethod;
+    /** Path and query under the API base, e.g. `/api/assistant/jobs` (the gateway's `http.base`). */
+    readonly path: string;
+    /** Request body (JSON text); sent as `application/json`. Not allowed with `GET`. */
+    readonly body?: string;
+    /**
+     * An explicit Console credential (`ZHIN_CONSOLE_TOKEN`): the gateway authenticates it like the
+     * HTTP route does and runs the request as that principal (permissions, audit). Without it the
+     * request runs as the local owner.
+     */
+    readonly token?: string;
+}
+export interface LocalGatewayHttpResponse {
+    readonly status: number;
+    /** `content-type` and `retry-after` when present. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Response body as text. */
+    readonly body: string;
+}
+export type LocalGatewayRpcType = (typeof LOCAL_GATEWAY_RPC)[keyof typeof LOCAL_GATEWAY_RPC];
+/** Longest accepted line in either direction (UTF-8 bytes). */
+export declare const MAX_LOCAL_LINE_BYTES: number;
+/**
+ * Largest `gateway.http.request` body / response body, in UTF-8 bytes of its JSON-encoded form:
+ * the line limit minus room for the envelope (`id`, `type`, path, headers…). Larger ones get an
+ * error telling the caller to use HTTP instead.
+ */
+export declare const MAX_LOCAL_HTTP_BODY_BYTES: number;
+export interface LocalGatewayRequest {
+    readonly id: number | string;
+    readonly type: string;
+    readonly data?: unknown;
+}
+/** Gateway RPC codes, plus the Console account codes of the `gateway.console.*` RPC. */
+export type LocalGatewayErrorCode = GatewayRpcErrorCode | 'not_found' | 'last_owner' | 'unauthorized' | 'rate_limited' | 'database_busy';
+/** `errors` / `missingEnv` as in the HTTP reply ({@link GatewayRpcErrorDetails}), only when non-empty. */
+export interface LocalGatewayError extends GatewayRpcErrorDetails {
+    readonly code: LocalGatewayErrorCode;
+    readonly message: string;
+    readonly status: number;
+}
+export type LocalGatewayResponse = Readonly<{
+    id: number | string;
+    ok: true;
+    data: unknown;
+}> | Readonly<{
+    id: number | string;
+    ok: false;
+    error: LocalGatewayError;
+}>;
+export interface LocalGatewayEventLine {
+    readonly id: number | string;
+    readonly event: GatewayPackageEvent;
+}
+export type LocalGatewayServerLine = LocalGatewayResponse | LocalGatewayEventLine;
+/** `.zhin/gateway.json` and the `gateway.info` answer. */
+export interface LocalGatewayInfo {
+    readonly pid: number;
+    /** Ports of the gateway's HTTP listeners. */
+    readonly ports: readonly number[];
+    /** Listener origins (`http://127.0.0.1:8068`). */
+    readonly origins: readonly string[];
+    /** Local control endpoint (socket path or pipe name). */
+    readonly socket: string;
+    /** Epoch ms. */
+    readonly startedAt: number;
+    /** `@zhin.js/gateway` version. */
+    readonly version: string;
+    /** `foreground` (attached to a terminal / service manager) or `daemon` (`zhin start`). */
+    readonly mode: 'foreground' | 'daemon';
+    /** Start options the instance runs with (re-used by `zhin restart --gateway`). */
+    readonly args: readonly string[];
+    /** Instance log file. */
+    readonly logFile?: string;
+    /**
+     * Key of the {@link LOCAL_GATEWAY_RPC.HELLO} handshake (hex). Only in the state file (mode
+     * 0600), never in the `gateway.info` answer.
+     */
+    readonly handshakeKey?: string;
+}
+export interface LocalGatewayInfoResult {
+    readonly gateway: LocalGatewayInfo;
+    readonly instance: GatewayInstanceStatus;
+    /** False until the first Console owner exists (the bootstrap token still works). */
+    readonly consoleInitialized: boolean;
+}
+/** The {@link LOCAL_GATEWAY_RPC.HELLO} proof for `nonce` under a hex `key`. */
+export declare function handshakeProof(key: string, nonce: string): string;
+/** Splits a stream into lines, refusing lines longer than {@link MAX_LOCAL_LINE_BYTES} (UTF-8). */
+export declare class LineDecoder {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes?: number);
+    /** Returns the complete lines in `chunk`; throws when a line exceeds the limit. */
+    push(chunk: string): string[];
+}

package/lib/local/protocol.js

@@ -0,0 +1,90 @@
+/**
+ * JSON-lines protocol of the local control socket (ADR 0054 §6). One request per line:
+ * `{ id, type, data? }`; the gateway answers each with `{ id, ok, data | error }` and may send
+ * `{ id, event }` lines before it (package transaction progress). `type` is a `gateway.*` RPC
+ * type (answered with principal `'local'`) or one of the local-only {@link LOCAL_GATEWAY_RPC}.
+ */
+import { createHmac } from 'node:crypto';
+/** Socket-only RPC: not reachable over HTTP. */
+export const LOCAL_GATEWAY_RPC = Object.freeze({
+    /**
+     * `{ nonce }` → `{ proof }`: HMAC-SHA256 of `nonce` under the run's handshake key (recorded only
+     * in the 0600 `.zhin/gateway.json`). The CLI sends it first and refuses an endpoint that cannot
+     * prove it is this project's gateway (a squatted Windows named pipe). Answered before any other
+     * request, also while the gateway is still starting.
+     */
+    HELLO: 'gateway.hello',
+    /** Gateway process info and instance status. */
+    INFO: 'gateway.info',
+    /** Stops the instance, then the gateway. */
+    SHUTDOWN: 'gateway.shutdown',
+    /**
+     * `zhin console init` beside a running gateway (ADR 0049 §7): the gateway's own
+     * `ConsoleSetupService` answers, so a database switch is applied live (reconnect + instance
+     * restart) and the owner state changes at once.
+     */
+    CONSOLE_SETUP_STATUS: 'gateway.console.setup.status',
+    CONSOLE_SETUP_DRIVERS: 'gateway.console.setup.drivers',
+    /** `{ dialect, connection }` → the probe result. */
+    CONSOLE_SETUP_DATABASE_TEST: 'gateway.console.setup.database.test',
+    /** `{ dialect, connection }`: writes the config, reconnects the gateway, restarts the instance. */
+    CONSOLE_SETUP_DATABASE: 'gateway.console.setup.database',
+    /** `{ username, password, displayName? }`: the first owner. */
+    CONSOLE_SETUP_OWNER: 'gateway.console.setup.owner',
+    /** `zhin console user …` beside a running gateway: the gateway's `ConsoleIamService` answers. */
+    CONSOLE_USER_LIST: 'gateway.console.user.list',
+    /** `{ username, password, displayName?, role }`. */
+    CONSOLE_USER_CREATE: 'gateway.console.user.create',
+    /** `{ username, password }`: resets the password (revokes the user's sessions). */
+    CONSOLE_USER_PASSWD: 'gateway.console.user.passwd',
+    /** `{ username, disabled }`. */
+    CONSOLE_USER_DISABLE: 'gateway.console.user.disable',
+    /**
+     * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
+     * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no
+     * Console token (ADR 0054 §6). Answered like the HTTP route ({@link LocalGatewayHttpResponse}).
+     */
+    HTTP_REQUEST: 'gateway.http.request',
+});
+/** Longest accepted line in either direction (UTF-8 bytes). */
+export const MAX_LOCAL_LINE_BYTES = 1024 * 1024;
+/**
+ * Largest `gateway.http.request` body / response body, in UTF-8 bytes of its JSON-encoded form:
+ * the line limit minus room for the envelope (`id`, `type`, path, headers…). Larger ones get an
+ * error telling the caller to use HTTP instead.
+ */
+export const MAX_LOCAL_HTTP_BODY_BYTES = MAX_LOCAL_LINE_BYTES - 16 * 1024;
+/** The {@link LOCAL_GATEWAY_RPC.HELLO} proof for `nonce` under a hex `key`. */
+export function handshakeProof(key, nonce) {
+    return createHmac('sha256', Buffer.from(key, 'hex')).update(nonce).digest('hex');
+}
+/** Splits a stream into lines, refusing lines longer than {@link MAX_LOCAL_LINE_BYTES} (UTF-8). */
+export class LineDecoder {
+    maxBytes;
+    #buffer = '';
+    constructor(maxBytes = MAX_LOCAL_LINE_BYTES) {
+        this.maxBytes = maxBytes;
+    }
+    /** Returns the complete lines in `chunk`; throws when a line exceeds the limit. */
+    push(chunk) {
+        this.#buffer += chunk;
+        const lines = [];
+        for (;;) {
+            const newline = this.#buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > this.maxBytes) {
+                this.#buffer = '';
+                throw new Error('line too long');
+            }
+            lines.push(line);
+        }
+        if (Buffer.byteLength(this.#buffer) > this.maxBytes) {
+            this.#buffer = '';
+            throw new Error('line too long');
+        }
+        return lines.filter((line) => line.trim().length > 0);
+    }
+}

package/lib/local/state-file.d.ts

@@ -0,0 +1,8 @@
+import type { LocalGatewayInfo } from './protocol.js';
+/** Atomically writes the info file with mode 0600. */
+export declare function writeGatewayInfo(root: string, info: LocalGatewayInfo): Promise<string>;
+/** The info file, or undefined when missing or unreadable. */
+export declare function readGatewayInfo(root: string): Promise<LocalGatewayInfo | undefined>;
+export declare function readGatewayInfoSync(root: string): LocalGatewayInfo | undefined;
+/** Removes the info file when it still belongs to `pid`. */
+export declare function removeGatewayInfo(root: string, pid?: number): Promise<void>;

package/lib/local/state-file.js

@@ -0,0 +1,45 @@
+/** `.zhin/gateway.json`: written by a running gateway, removed when it stops. */
+import { readFileSync } from 'node:fs';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { gatewayInfoFile } from './paths.js';
+/** Atomically writes the info file with mode 0600. */
+export async function writeGatewayInfo(root, info) {
+    const file = gatewayInfoFile(root);
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+    await chmod(temporary, 0o600).catch(() => undefined);
+    await rename(temporary, file);
+    return file;
+}
+/** The info file, or undefined when missing or unreadable. */
+export async function readGatewayInfo(root) {
+    try {
+        return parseInfo(await readFile(gatewayInfoFile(root), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readGatewayInfoSync(root) {
+    try {
+        return parseInfo(readFileSync(gatewayInfoFile(root), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Removes the info file when it still belongs to `pid`. */
+export async function removeGatewayInfo(root, pid = process.pid) {
+    const current = await readGatewayInfo(root);
+    if (current && current.pid !== pid)
+        return;
+    await rm(gatewayInfoFile(root), { force: true });
+}
+function parseInfo(text) {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || typeof value.pid !== 'number' || typeof value.socket !== 'string')
+        return undefined;
+    return value;
+}

package/lib/local.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@zhin.js/gateway/local` — the gateway's local control socket (ADR 0054 §6): paths, the
+ * JSON-lines protocol, the server, the CLI client and `.zhin/gateway.json`. No Node HTTP stack.
+ */
+export * from './local/paths.js';
+export * from './local/protocol.js';
+export * from './local/local-socket.js';
+export * from './local/handler.js';
+export * from './local/client.js';
+export * from './local/state-file.js';

package/lib/local.js

@@ -0,0 +1,10 @@
+/**
+ * `@zhin.js/gateway/local` — the gateway's local control socket (ADR 0054 §6): paths, the
+ * JSON-lines protocol, the server, the CLI client and `.zhin/gateway.json`. No Node HTTP stack.
+ */
+export * from './local/paths.js';
+export * from './local/protocol.js';
+export * from './local/local-socket.js';
+export * from './local/handler.js';
+export * from './local/client.js';
+export * from './local/state-file.js';