@nidl/client 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,817 @@
+// @nidl/client: drive a running nidl core from a Node program, over its local socket, as the
+// `app` client kind (docs/protocol/nidl-core-protocol.md). It never starts a core, and it checks
+// the folder the socket lives in before trusting it. With a URL and a remote token it reaches a
+// core on another machine through its remote port, over HTTPS (docs/specs/nidl-remote-mode.md s.5).
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { createConnection, isIP } from "node:net";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, sep } from "node:path";
+import { connect as tlsConnect } from "node:tls";
+import { parseStrict } from "./json.js";
+export const VERSION = "0.1.0";
+const MAX_RECORD = 16 * 1024;
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+const MAX_LINE = 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** The longest socket path the platform takes, without its NUL. */
+const MAX_SOCKET_PATH = process.platform === "darwin" ? 103 : 107;
+/** PQ4: the most a secret frame's payload may be, as the core bounds it. */
+const MAX_SECRET = 64 * 1024;
+/**
+ * Why a call failed. `code` is for programs and `message` for people. `outcome` says whether
+ * anything happened: `not_started`, or `unknown` when the connection was lost after the request
+ * was sent.
+ */
+export class NidlError extends Error {
+    code;
+    outcome;
+    name = "NidlError";
+    constructor(code, message, outcome = "not_started") {
+        super(message);
+        this.code = code;
+        this.outcome = outcome;
+    }
+}
+/**
+ * Connect to the core serving `dataDir`, or, with `url` and `token`, to the core whose remote port
+ * is at `url`; then say hello once to prove it answers.
+ */
+export async function connect(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let nidl;
+    if (options.url !== undefined || options.token !== undefined || options.fingerprint !== undefined) {
+        if (options.dataDir !== undefined) {
+            throw new NidlError("invalid_input", "Name one core: a data folder, or a remote URL.");
+        }
+        if (options.url === undefined || options.token === undefined) {
+            throw new NidlError("invalid_input", "A remote core needs both its URL and a remote token.");
+        }
+        nidl = new Nidl(undefined, timeoutMs, new Remote(options.url, options.token, options.fingerprint));
+    }
+    else {
+        nidl = new Nidl(options.dataDir ?? join(homedir(), ".nidl"), timeoutMs);
+    }
+    await nidl.refresh();
+    return nidl;
+}
+export class Nidl {
+    dataDir;
+    timeoutMs;
+    remote;
+    #identity;
+    /** @internal Use `connect()`. */
+    constructor(
+    /** The data folder of the core on this machine; undefined for a remote core. */
+    dataDir, timeoutMs, remote) {
+        this.dataDir = dataDir;
+        this.timeoutMs = timeoutMs;
+        this.remote = remote;
+    }
+    /** The core's identity from the latest hello. */
+    get identity() {
+        if (!this.#identity) {
+            throw new NidlError("not_connected", "Call connect() first.");
+        }
+        return this.#identity;
+    }
+    /** Whether the core offers a command, by the latest hello. */
+    has(name) {
+        return this.identity.commands.includes(name);
+    }
+    /**
+     * Run one command and return its result, or throw a `NidlError`. Each call opens its own
+     * connection, checks the folder again and says hello again. `name` is one an app may run
+     * (CL8); a newer core's command is called with a cast, `"its.name" as CommandName`.
+     */
+    async command(name, args = {}) {
+        // PQ4: a key goes in the socket's secret frame, never in a command's arguments. The type
+        // leaves `pools.lend` out; this refuses it from JavaScript, or through a cast.
+        if (name === "pools.lend") {
+            throw new NidlError("invalid_input", "pools.lend takes a key; call lend(), which sends it in the socket's secret frame.");
+        }
+        this.offered(name);
+        const reply = await this.exchange({ name, version: 1, arguments: args, requestId: randomUUID() });
+        return commandResult(reply);
+    }
+    /**
+     * PQ4 (docs/specs/nidl-external-pools.md s.6 item 1): lend `apiKey` to the borrowed account
+     * `accountId` of the core on this machine. An app proves the account's project with
+     * `appToken`, an app token of one of that project's targets. The key travels in the socket's
+     * secret frame, never in the command's arguments, and never through the remote port. A
+     * JavaScript string cannot be wiped; the frame's own bytes are overwritten once written.
+     */
+    async lend(accountId, apiKey, options = {}) {
+        this.onThisMachine();
+        this.offered("pools.lend");
+        const args = { accountId };
+        if (options.expiresInSeconds !== undefined)
+            args.expiresInSeconds = options.expiresInSeconds;
+        const frame = { credential: { apiKey } };
+        if (options.appToken !== undefined)
+            frame.appToken = options.appToken;
+        const secret = secretFrame(Buffer.from(JSON.stringify(frame)));
+        let reply;
+        try {
+            reply = await this.exchange({ name: "pools.lend", version: 1, arguments: args, requestId: randomUUID() }, secret);
+        }
+        finally {
+            // However the call ended, before the frame was written included (the scoped review, m3).
+            secret.fill(0);
+        }
+        return commandResult(reply);
+    }
+    /**
+     * PQ4: end the lease of the borrowed account `accountId` on the core on this machine.
+     * Withdrawing none is not an error: the result says whether there was one.
+     */
+    async withdraw(accountId) {
+        this.onThisMachine();
+        return this.command("pools.withdraw", { accountId });
+    }
+    /**
+     * PQ4: report an observed account's quota readings, on this machine or through the remote port
+     * with a remote token bound to the account's project. `capturedAt` (RFC 3339) defaults to now.
+     */
+    async observe(accountId, windows, capturedAt) {
+        const args = { accountId, windows };
+        if (capturedAt !== undefined)
+            args.capturedAt = capturedAt;
+        return this.command("readings.observe", args);
+    }
+    onThisMachine() {
+        if (this.remote) {
+            throw new NidlError("unsupported", "A key is lent and withdrawn only on the nidl core on this machine, never through the remote port.");
+        }
+    }
+    offered(name) {
+        if (!this.has(name)) {
+            throw new NidlError("not_offered", `This nidl core (version ${this.identity.coreVersion}) does not offer ${name}; update nidl.`);
+        }
+    }
+    /** @internal Say hello on a fresh connection and keep the identity. */
+    async refresh() {
+        await this.exchange(undefined);
+    }
+    /** `secret`, when given, is the secret frame written right after the command's line (PQ4). */
+    async exchange(execute, secret) {
+        if (this.remote) {
+            const deadline = Date.now() + this.timeoutMs;
+            if (execute === undefined) {
+                this.#identity = await this.remote.hello(deadline);
+                return this.#identity;
+            }
+            return this.remote.command(String(execute.name), execute.arguments, deadline);
+        }
+        const namespace = await checkedNamespace(this.dataDir ?? join(homedir(), ".nidl"));
+        const connection = await Connection.open(namespace, this.timeoutMs);
+        try {
+            await connection.afterConnect(namespace);
+            const identity = await connection.hello(namespace);
+            this.#identity = identity;
+            if (execute === undefined) {
+                await verifyUnchanged(namespace);
+                return identity;
+            }
+            const reply = await connection.request("command.execute", execute, secret);
+            try {
+                await verifyUnchanged(namespace);
+            }
+            catch (error) {
+                // CLb s.10 item 1: the command was sent and may have run, whatever the check found.
+                if (error instanceof NidlError)
+                    throw new NidlError(error.code, error.message, "unknown");
+                throw error;
+            }
+            return reply;
+        }
+        finally {
+            connection.close();
+        }
+    }
+}
+function startHint(dataDir) {
+    return `No nidl core is running for ${dataDir}. Start one with: nidl serve --data-dir ${dataDir}`;
+}
+function unsafe(what) {
+    return new NidlError("unsafe_folder", `${what}, so nidl's socket there cannot be trusted. Check its owner and mode.`);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalNumber(value) {
+    return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
+}
+function errorCode(error) {
+    return isObject(error) && typeof error.code === "string" ? error.code : undefined;
+}
+/** The checks of the protocol's s.2 item 2 that Node can make: owners, modes, the record, the socket. */
+async function checkedNamespace(dataDir) {
+    if (process.platform !== "darwin" && process.platform !== "linux") {
+        throw new NidlError("unsupported", "nidl runs on macOS and Linux only.");
+    }
+    const uid = process.geteuid?.();
+    if (uid === undefined) {
+        throw new NidlError("unsupported", "This platform has no user ids.");
+    }
+    let real;
+    try {
+        real = await realpath(dataDir);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            throw new NidlError("not_running", startHint(dataDir));
+        throw unsafe(`The data folder ${dataDir} cannot be read`);
+    }
+    if (!isAbsolute(real) || real.split(sep).includes("..")) {
+        throw unsafe(`The data folder ${dataDir} is not an absolute path`);
+    }
+    // Every folder from / down to the data folder: a folder, the user's or root's, and not writable
+    // by group or others.
+    const chain = [];
+    for (let path = real;; path = dirname(path)) {
+        chain.unshift(path);
+        if (dirname(path) === path)
+            break;
+    }
+    for (const path of chain) {
+        const stats = await lstat(path, { bigint: true }).catch(() => {
+            throw unsafe(`${path} cannot be read`);
+        });
+        if (!stats.isDirectory() ||
+            (stats.uid !== BigInt(uid) && stats.uid !== 0n) ||
+            (stats.mode & 18n) !== 0n) {
+            throw unsafe(`${path} is writable by others or owned by another user`);
+        }
+    }
+    const control = join(real, ".nidl-runtime");
+    const controlStats = await lstatOrNotRunning(control, dataDir);
+    if (!controlStats.isDirectory() ||
+        controlStats.uid !== BigInt(uid) ||
+        (controlStats.mode & 4095n) !== 448n) {
+        throw unsafe(`${control} is not a folder only you can use`);
+    }
+    const recordPath = join(control, "core-info.json");
+    const recordText = await readRecord(recordPath, dataDir, uid);
+    const record = parseRecord(recordText, {
+        device: controlStats.dev.toString(),
+        inode: controlStats.ino.toString(),
+    });
+    const socketPath = join(control, "core.sock");
+    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
+        throw new NidlError("path_too_long", `The socket path ${socketPath} is longer than this platform allows (${MAX_SOCKET_PATH} bytes); use a shorter data folder.`);
+    }
+    const namespace = { dataDir, socketPath, recordPath, recordText, record };
+    await checkSocket(namespace, uid);
+    return namespace;
+}
+async function lstatOrNotRunning(path, dataDir) {
+    try {
+        return await lstat(path, { bigint: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            throw new NidlError("not_running", startHint(dataDir));
+        throw unsafe(`${path} cannot be read`);
+    }
+}
+async function readRecord(path, dataDir, uid) {
+    const stats = await lstatOrNotRunning(path, dataDir);
+    if (!stats.isFile() ||
+        stats.nlink !== 1n ||
+        stats.uid !== BigInt(uid) ||
+        (stats.mode & 4095n) !== 384n ||
+        stats.size > BigInt(MAX_RECORD)) {
+        throw unsafe(`${path} is not a private record`);
+    }
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => {
+        throw unsafe(`${path} cannot be opened`);
+    });
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (opened.dev !== stats.dev || opened.ino !== stats.ino) {
+            throw unsafe(`${path} changed while it was read`);
+        }
+        const buffer = Buffer.alloc(MAX_RECORD + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_RECORD) {
+            throw unsafe(`${path} is too long`);
+        }
+        // CLb s.10 item 7: invalid UTF-8 is refused, never replaced.
+        try {
+            return strictUtf8.decode(buffer.subarray(0, bytesRead));
+        }
+        catch {
+            throw unsafe(`${path} is not UTF-8 text`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function parseRecord(text, root) {
+    let value;
+    try {
+        value = parseStrict(text, { integersOnly: true });
+    }
+    catch {
+        throw unsafe("The core's record is not one JSON object");
+    }
+    if (!isObject(value) ||
+        Object.keys(value).sort().join(",") !== "endpoint,runtime,schemaVersion,socket" ||
+        value.schemaVersion !== 1 ||
+        value.endpoint !== "core.sock" ||
+        !isObject(value.socket) ||
+        Object.keys(value.socket).sort().join(",") !== "device,inode" ||
+        !canonicalNumber(value.socket.device) ||
+        !canonicalNumber(value.socket.inode) ||
+        !isObject(value.runtime) ||
+        !isObject(value.runtime.root) ||
+        value.runtime.root.device !== root.device ||
+        value.runtime.root.inode !== root.inode ||
+        typeof value.runtime.instanceNonce !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.runtime.instanceNonce)) {
+        throw unsafe("The core's record does not describe this folder's core");
+    }
+    if (value.runtime.apiMajor !== 1) {
+        throw new NidlError("version_conflict", `This nidl core speaks protocol version ${String(value.runtime.apiMajor)}; this library speaks 1.`);
+    }
+    return {
+        socket: { device: value.socket.device, inode: value.socket.inode },
+        runtime: value.runtime,
+    };
+}
+async function checkSocket(namespace, uid) {
+    const stats = await lstatOrNotRunning(namespace.socketPath, namespace.dataDir);
+    if (!stats.isSocket() ||
+        stats.nlink !== 1n ||
+        stats.uid !== BigInt(uid) ||
+        (stats.mode & 4095n) !== 384n ||
+        stats.dev.toString() !== namespace.record.socket.device ||
+        stats.ino.toString() !== namespace.record.socket.inode) {
+        throw unsafe(`${namespace.socketPath} is not the socket the core's record names`);
+    }
+}
+/** After a reply: the record and the socket are still the ones checked before connecting. */
+async function verifyUnchanged(namespace) {
+    const uid = process.geteuid?.() ?? -1;
+    const text = await readRecord(namespace.recordPath, namespace.dataDir, uid);
+    if (text !== namespace.recordText) {
+        throw unsafe("The core's record changed during the call");
+    }
+    await checkSocket(namespace, uid);
+}
+/**
+ * PQ4: the socket's secret frame (docs/protocol/nidl-core-protocol.md s.8): `NSF1`, the payload's
+ * length as a big-endian u32, the payload, and a newline. The payload is overwritten here.
+ */
+function secretFrame(payload) {
+    if (payload.length === 0 || payload.length > MAX_SECRET) {
+        payload.fill(0);
+        throw new NidlError("invalid_input", "The key and its app token are longer than the core accepts (64 KiB).");
+    }
+    const frame = Buffer.alloc(payload.length + 9);
+    frame.write("NSF1", 0, "latin1");
+    frame.writeUInt32BE(payload.length, 4);
+    payload.copy(frame, 8);
+    frame[frame.length - 1] = 0x0a;
+    payload.fill(0);
+    return frame;
+}
+function commandResult(reply) {
+    if (!isObject(reply) || typeof reply.ok !== "boolean") {
+        throw new NidlError("protocol_error", "The core's reply is not a command reply.");
+    }
+    if (reply.ok) {
+        return reply.result;
+    }
+    const error = reply.error;
+    if (!isObject(error) || typeof error.code !== "string" || typeof error.message !== "string") {
+        throw new NidlError("protocol_error", "The core's reply is not a command reply.");
+    }
+    throw new NidlError(error.code, error.message, typeof error.outcome === "string" ? error.outcome : "not_started");
+}
+/** One connection: hello, at most one request, closed. */
+class Connection {
+    socket;
+    buffer = Buffer.alloc(0);
+    waiting;
+    failure;
+    written = false;
+    deadline;
+    constructor(socket, timeoutMs) {
+        this.socket = socket;
+        this.deadline = Date.now() + timeoutMs;
+        socket.on("data", (chunk) => this.received(chunk));
+        socket.on("error", (error) => this.fail(error));
+        socket.on("close", () => this.fail(new Error("closed")));
+    }
+    static open(namespace, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ path: namespace.socketPath });
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new NidlError("timeout", "The nidl core did not accept the connection in time."));
+            }, timeoutMs);
+            socket.once("connect", () => {
+                clearTimeout(timer);
+                socket.removeAllListeners("error");
+                resolve(new Connection(socket, timeoutMs));
+            });
+            socket.once("error", (error) => {
+                clearTimeout(timer);
+                const code = errorCode(error);
+                reject(code === "ECONNREFUSED" || code === "ENOENT"
+                    ? new NidlError("not_running", startHint(namespace.dataDir))
+                    : new NidlError("unavailable", `The nidl core's socket could not be reached (${code ?? "error"}).`));
+            });
+        });
+    }
+    /** Node cannot ask for the peer's user, so the socket is checked again once connected. */
+    async afterConnect(namespace) {
+        await checkSocket(namespace, process.geteuid?.() ?? -1);
+    }
+    async hello(namespace) {
+        const runtime = namespace.record.runtime;
+        const result = await this.request("runtime.hello", {
+            apiMajor: 1,
+            apiMinor: 0,
+            clientKind: "app",
+            clientVersion: VERSION,
+            expectedRoot: runtime.root,
+            expectedInstance: runtime.instanceNonce,
+        });
+        if (!isObject(result) ||
+            !isObject(result.root) ||
+            result.root.device !== runtime.root.device ||
+            result.root.inode !== runtime.root.inode ||
+            result.instanceNonce !== runtime.instanceNonce ||
+            result.apiMajor !== 1 ||
+            typeof result.coreVersion !== "string" ||
+            !Array.isArray(result.commands) ||
+            !result.commands.every((name) => typeof name === "string")) {
+            throw new NidlError("protocol_error", "The nidl core's hello does not match its record.");
+        }
+        return result;
+    }
+    async request(method, params, secret) {
+        const id = randomUUID();
+        const line = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
+        if (Buffer.byteLength(line) > MAX_LINE) {
+            secret?.fill(0);
+            throw new NidlError("invalid_input", "The request is larger than the core accepts (1 MiB).");
+        }
+        this.socket.write(line);
+        this.written = method === "command.execute";
+        if (secret) {
+            // PQ4: the secret frame follows its command's line at once, and is overwritten once the
+            // socket has taken it (or failed to).
+            this.socket.write(secret, () => secret.fill(0));
+        }
+        const bytes = await this.line();
+        let reply;
+        try {
+            reply = parseStrict(strictUtf8.decode(bytes));
+        }
+        catch {
+            throw new NidlError("protocol_error", "The nidl core's reply is not JSON.", this.outcome());
+        }
+        if (!isObject(reply) || reply.jsonrpc !== "2.0" || reply.id !== id) {
+            throw new NidlError("protocol_error", "The nidl core's reply does not answer this request.", this.outcome());
+        }
+        if (isObject(reply.error)) {
+            const data = isObject(reply.error.data) ? reply.error.data : {};
+            throw new NidlError(typeof data.code === "string" ? data.code : "protocol_error", typeof reply.error.message === "string" ? reply.error.message : "The nidl core refused the request.", typeof data.outcome === "string" ? data.outcome : "not_started");
+        }
+        if (!("result" in reply)) {
+            throw new NidlError("protocol_error", "The nidl core's reply has no result.", this.outcome());
+        }
+        return reply.result;
+    }
+    close() {
+        this.socket.destroy();
+    }
+    outcome() {
+        return this.written ? "unknown" : "not_started";
+    }
+    line() {
+        const ready = this.take();
+        if (ready !== undefined)
+            return Promise.resolve(ready);
+        if (this.failure)
+            return Promise.reject(this.lost());
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.waiting = undefined;
+                this.socket.destroy();
+                reject(new NidlError("timeout", "The nidl core did not answer in time.", this.outcome()));
+            }, Math.max(0, this.deadline - Date.now()));
+            this.waiting = (line) => {
+                clearTimeout(timer);
+                this.waiting = undefined;
+                if (line instanceof Error)
+                    reject(line);
+                else
+                    resolve(line);
+            };
+        });
+    }
+    take() {
+        const end = this.buffer.indexOf(0x0a);
+        if (end < 0)
+            return undefined;
+        const line = Buffer.from(this.buffer.subarray(0, end));
+        this.buffer = this.buffer.subarray(end + 1);
+        return line;
+    }
+    received(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        if (this.buffer.indexOf(0x0a) < 0 && this.buffer.length > MAX_LINE) {
+            this.failure = new NidlError("protocol_error", "The nidl core's reply is longer than 1 MiB.", this.outcome());
+            this.socket.destroy();
+            this.waiting?.(this.failure);
+            return;
+        }
+        // A line is taken only for a request waiting on it; otherwise it stays for the next `line()`.
+        if (this.waiting) {
+            const line = this.take();
+            if (line !== undefined)
+                this.waiting(line);
+        }
+    }
+    fail(error) {
+        if (this.failure)
+            return;
+        this.failure = error;
+        this.waiting?.(this.lost());
+    }
+    lost() {
+        if (this.failure instanceof NidlError)
+            return this.failure;
+        return new NidlError("unavailable", "The connection to the nidl core was lost.", this.outcome());
+    }
+}
+// NR3 (docs/specs/nidl-remote-mode.md s.5): a core's remote port, over HTTPS.
+/** The most a command's body may be, and the most an answer may be. */
+const MAX_BODY = 1024 * 1024;
+const MAX_ANSWER = 2 * 1024 * 1024;
+function invalid(message) {
+    return new NidlError("invalid_input", message);
+}
+/** `https://host[:port][/]`: nothing else, so a token never goes in plain text or to a path the caller did not mean. */
+function parseUrl(url) {
+    if (!url.startsWith("https://")) {
+        throw invalid("A remote nidl is reached over https://, never plain http.");
+    }
+    let authority = url.slice("https://".length);
+    if (authority.endsWith("/"))
+        authority = authority.slice(0, -1);
+    // A name, an IPv4 address, or an IPv6 address in brackets, and a port: nothing that could
+    // become another header or another place (NR3's review, m4).
+    if (!/^[A-Za-z0-9.:[\]-]+$/.test(authority)) {
+        throw invalid("A remote nidl's URL is https://HOST[:PORT], with no path, query or user.");
+    }
+    let host;
+    let portText;
+    if (authority.startsWith("[")) {
+        const close = authority.indexOf("]");
+        if (close < 0)
+            throw invalid("The URL's IPv6 address has no closing bracket.");
+        host = authority.slice(1, close);
+        const after = authority.slice(close + 1);
+        if (after !== "" && !after.startsWith(":")) {
+            throw invalid("After an IPv6 address's bracket comes only :PORT.");
+        }
+        if (isIP(host) !== 6)
+            throw invalid("The URL's brackets hold no IPv6 address.");
+        portText = after === "" ? undefined : after.slice(1);
+    }
+    else {
+        const colon = authority.indexOf(":");
+        host = colon < 0 ? authority : authority.slice(0, colon);
+        portText = colon < 0 ? undefined : authority.slice(colon + 1);
+    }
+    if (/[[\]]/.test(host))
+        throw invalid("The URL names no host.");
+    let port = 443;
+    if (portText !== undefined) {
+        if (!/^[0-9]{1,5}$/.test(portText) || Number(portText) < 1 || Number(portText) > 65535) {
+            throw invalid("The URL's port is not a number from 1 to 65535.");
+        }
+        port = Number(portText);
+    }
+    if (host === "")
+        throw invalid("The URL names no host.");
+    return { host, port, authority };
+}
+/** `sha256:` and 64 hex digits, as `nidl remote status` shows it. */
+function parseFingerprint(fingerprint) {
+    const match = /^sha256:([0-9a-fA-F]{64})$/.exec(fingerprint);
+    if (!match?.[1]) {
+        throw invalid("A fingerprint is sha256: and 64 hex digits, as `nidl remote status` shows it.");
+    }
+    return Buffer.from(match[1], "hex");
+}
+function timeLeft(deadline) {
+    const left = deadline - Date.now();
+    if (left <= 0)
+        throw new NidlError("timeout", "The remote nidl did not answer in time.");
+    return left;
+}
+/**
+ * A core's remote port: one TLS connection per call, closed after the answer. The certificate is
+ * checked once the handshake is done and before anything is written, so a token is never sent to a
+ * server that is not the core's. With a pin, the handshake's own signature still proves the server
+ * holds the pinned certificate's key.
+ */
+class Remote {
+    host;
+    port;
+    authority;
+    pin;
+    /** A true private field, so `console.log` and `util.inspect` never show it (NR3's review, M2). */
+    #token;
+    constructor(url, token, fingerprint) {
+        ({ host: this.host, port: this.port, authority: this.authority } = parseUrl(url));
+        if (typeof token !== "string" || token.length === 0 || token.length > 256 || !/^[!-~]+$/.test(token)) {
+            throw invalid("A remote token is the printable text `nidl remote-tokens issue` gave.");
+        }
+        this.#token = token;
+        this.pin = fingerprint === undefined ? undefined : parseFingerprint(fingerprint);
+    }
+    async hello(deadline) {
+        const { status, body } = await this.exchange("GET", "/nidl/v1/hello", undefined, deadline);
+        const identity = this.answer(status, body, false);
+        if (!isObject(identity)) {
+            throw new NidlError("protocol_error", "The remote nidl's hello is not a core's identity.");
+        }
+        if (identity.apiMajor !== 1) {
+            throw new NidlError("version_conflict", `This nidl core speaks protocol version ${String(identity.apiMajor)}; this library speaks 1.`);
+        }
+        if (typeof identity.coreVersion !== "string" ||
+            typeof identity.scope !== "string" ||
+            !Array.isArray(identity.commands) ||
+            !identity.commands.every((name) => typeof name === "string")) {
+            throw new NidlError("protocol_error", "The remote nidl's hello is not a core's identity.");
+        }
+        return identity;
+    }
+    async command(name, args, deadline) {
+        const body = Buffer.from(JSON.stringify({ name, arguments: args ?? {} }));
+        if (body.length > MAX_BODY) {
+            throw invalid("The command is larger than a remote nidl accepts (1 MiB).");
+        }
+        const answer = await this.exchange("POST", "/nidl/v1/command", body, deadline);
+        return this.answer(answer.status, answer.body, true);
+    }
+    /** A reply or an identity for 200, a reply for the 403 and 502 that carry one; otherwise the error the status names. */
+    answer(status, body, command) {
+        let parsed;
+        try {
+            parsed = parseStrict(strictUtf8.decode(body));
+        }
+        catch {
+            parsed = undefined;
+        }
+        const said = isObject(parsed) && typeof parsed.error === "string" ? parsed.error : undefined;
+        // A 403 or a 502 carries a reply only as a refusal (NR3's review, m7).
+        const carriesReply = isObject(parsed) && parsed.ok === false;
+        const outcome = command ? "unknown" : "not_started";
+        if (status === 200) {
+            if (parsed === undefined)
+                throw new NidlError("protocol_error", "The remote nidl's answer is not JSON.", outcome);
+            return parsed;
+        }
+        if ((status === 403 || status === 502) && command && carriesReply)
+            return parsed;
+        switch (status) {
+            case 401:
+                throw new NidlError("unauthorized", "The remote nidl refused the token: it is unknown, revoked or expired.");
+            case 429:
+                throw new NidlError("throttled", said ?? "Too many failed attempts from this address; wait a minute.");
+            case 400:
+            case 413:
+                throw invalid(said ?? "The remote nidl refused the request.");
+            case 503:
+                throw new NidlError("unavailable", said ?? "The remote nidl is not serving commands now.");
+            case 404:
+                throw new NidlError("unsupported", "This nidl's remote port takes no commands; update nidl on that machine.");
+            case 403:
+                throw new NidlError("not_authorized", said ?? "The remote nidl refused the request.");
+            default:
+                throw new NidlError("protocol_error", `The remote nidl answered HTTP ${status}.`, outcome);
+        }
+    }
+    untrusted() {
+        return new NidlError("untrusted_certificate", `The remote nidl at ${this.authority} did not present the certificate expected of it; nothing was sent. ` +
+            "Check the fingerprint `nidl remote status` shows there.");
+    }
+    /** A TLS connection whose certificate has been checked, before anything is written on it. */
+    secured(deadline) {
+        const left = timeLeft(deadline);
+        return new Promise((resolve, reject) => {
+            const socket = tlsConnect({
+                host: this.host,
+                port: this.port,
+                ...(isIP(this.host) === 0 ? { servername: this.host } : {}),
+                rejectUnauthorized: this.pin === undefined,
+                minVersion: "TLSv1.2",
+                ALPNProtocols: ["http/1.1"],
+            });
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new NidlError("timeout", "The remote nidl did not accept the connection in time."));
+            }, left);
+            socket.once("secureConnect", () => {
+                clearTimeout(timer);
+                if (this.pin !== undefined) {
+                    const raw = socket.getPeerCertificate().raw;
+                    if (!raw || !createHash("sha256").update(raw).digest().equals(this.pin)) {
+                        socket.destroy();
+                        reject(this.untrusted());
+                        return;
+                    }
+                }
+                // The request's own handlers take over; this one keeps a late error from going unheard.
+                socket.on("error", () => { });
+                resolve(socket);
+            });
+            socket.once("error", (error) => {
+                clearTimeout(timer);
+                const code = errorCode(error) ?? "";
+                reject(/CERT|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)|ALTNAME/.test(code)
+                    ? this.untrusted()
+                    : new NidlError("unavailable", `The remote nidl at ${this.authority} could not be reached (${code || error.message}).`));
+            });
+        });
+    }
+    /** One request on one connection, every step within `deadline`. */
+    async exchange(method, path, body, deadline) {
+        const socket = await this.secured(deadline);
+        const outcome = method === "POST" ? "unknown" : "not_started";
+        const left = deadline - Date.now();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                socket.destroy();
+                if (result instanceof NidlError)
+                    reject(result);
+                else
+                    resolve(result);
+            };
+            const timer = setTimeout(() => settle(new NidlError("timeout", "The remote nidl did not answer in time.", outcome)), Math.max(0, left));
+            const request = httpRequest({
+                method,
+                path,
+                host: this.host,
+                port: this.port,
+                headers: {
+                    Host: this.authority,
+                    Authorization: `Bearer ${this.#token}`,
+                    "User-Agent": `nidl-client-node/${VERSION}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "Content-Length": String(body?.length ?? 0),
+                    Connection: "close",
+                },
+                createConnection: () => socket,
+            });
+            request.on("response", (response) => {
+                // The core always says its answer's length, so one framed only by the connection's end is
+                // refused, and a cut-off one is never taken as whole (NR3's review, m6).
+                const encoding = response.headers["transfer-encoding"];
+                if ((response.headers["content-length"] === undefined && encoding?.toLowerCase() !== "chunked") ||
+                    (encoding !== undefined && encoding.toLowerCase() !== "chunked")) {
+                    settle(new NidlError("protocol_error", "The remote nidl's answer is not framed as the core frames it.", outcome));
+                    return;
+                }
+                response.on("aborted", () => settle(new NidlError("unavailable", "The connection to the remote nidl was lost.", outcome)));
+                const chunks = [];
+                let size = 0;
+                response.on("data", (chunk) => {
+                    size += chunk.length;
+                    if (size > MAX_ANSWER) {
+                        settle(new NidlError("protocol_error", "The remote nidl's answer is too long.", outcome));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.on("end", () => settle({ status: response.statusCode ?? 0, body: Buffer.concat(chunks) }));
+                response.on("error", () => settle(new NidlError("unavailable", "The connection to the remote nidl was lost.", outcome)));
+            });
+            request.on("error", () => settle(new NidlError("unavailable", "The connection to the remote nidl was lost.", outcome)));
+            request.end(body ?? Buffer.alloc(0));
+        });
+    }
+}
+// CL8 (docs/specs/nidl-client-libraries.md s.11): the names an app may run, from the registry.
+export { COMMAND_NAMES } from "./commands.generated.js";
+// TQ3 (docs/specs/nidl-task-vaults.md D7): a Trigger.dev task's own core.
+export { openTaskCore, startTaskCore, TASK_VAULT_KEY_VARIABLE, TASK_VAULT_VARIABLE, } from "./task.js";
+//# sourceMappingURL=index.js.map