@hediet/linkrpc 0.0.1

package/dist/node.js

@@ -0,0 +1,1087 @@
+/*---------------------------------------------------------------------------------------------
+*  Copyright (c) Microsoft Corporation. All rights reserved.
+*  Licensed under the MIT License. See License.txt in the project root for license information.
+*--------------------------------------------------------------------------------------------*/
+import { A as NotificationType, C as defineInterface, D as sha256, E as computeInterfaceHash, F as normalizeJsonSchema, M as notificationType, N as requestType, O as jcsCanonicalize, P as zodToSvcJsonSchema, S as InterfaceDefinition, T as EXTENSION_PREFIX, _ as zTrafficEvent, a as topologyInterface, b as zTrafficTransitEvent, c as zParticipantDescriptorSource, d as zTopologyLink, f as zTopologyLinkEndpoint, g as zTopologyTransportInfo, h as zTopologyTransportEndpoint, i as nodeInterface, j as RequestType, k as jcsCanonicalizeBytes, l as zRouteClaim, m as zTopologyPort, o as trafficInterface, p as zTopologyNode, s as zParticipantDescriptor, u as zTopologyGraph, v as zTrafficOverflowEvent, w as interfaceFromSchema, x as zTrafficWatchResult, y as zTrafficTransitEndpoint } from "./chunks/boundedTrafficSubscription-1L592xc7.js";
+import { $t as bareInterfaceTarget, A as attachCapabilities, At as PRINCIPAL_PREFIX, B as LinkRpcConnection, Bt as isRequest, C as identityStorageInterface, Ct as getKeyId, D as PublicWrappingIdentity, Dt as signingInput, E as PublicSigningIdentity, Et as signingDomainValue, F as generateX25519Keypair, Ft as principalForPublicKey, Gt as StreamDir, H as JsonRpcChannel, Ht as STREAM_METHOD, I as formatEndpointUri, It as publicKeyForKeyId, Jt as directoryInterface, Kt as streamInterface, L as isHubEndpoint, Lt as resolveSigningKey, M as verifyRpcCall, Mt as bytesToBase64Url, N as crypto_exports, Nt as keyIdForPrincipal, O as Principal, Ot as withSignature, P as generateKeypair, Pt as keyIdForPublicKey, Qt as generateTsInterface, R as parseEndpointUri, Rt as ErrorCode, S as identityInterface, St as LINKRPC_UNSIGNED_KEY, T as KeypairSigningIdentity, Tt as signedHash, Ut as StreamControlReason, V as ServiceHandle, Vt as isResponse, Wt as StreamControlType, Xt as schemasInterface, Yt as directoryWatchNever, Zt as zServiceIdPattern, _ as InMemoryManagedIdentity, _t as HUBRPC_META_KEY, a as verifyCall, an as componentSchemaRef, at as TransportPair, b as registerIdentityOnOverlay, bt as LINKRPC_META_KEY, c as invoke, ct as requireObjectParams, d as prefix, dt as parseMethodName, en as createSchemaToZod, et as DEFAULT_RPC_TIMEOUT_MS, f as signCapability, ft as capabilityPermits, g as createManagedPrincipal, gt as permissionPermits, h as PrincipalWithStore, ht as permissionMatchesTarget, i as signParams, in as componentSchemaName, it as MultiplexedTransport, j as signRpcCall, jt as base64UrlToBytes, k as CapBag, kt as KEY_ID_PREFIX, l as issueCapability, lt as stripLinkRpcWireMeta, m as SigningSender, mt as matchParams, n as createSeededMemoryPrincipal, nn as materializeJsonSchema, nt as Channel, o as capBagFreshAt, on as isAssignable, ot as connectTransports, p as OneShotCapStaging, pt as hasSignedCapabilityShape, qt as defaultsInterface, r as createSeededSigningIdentity, rn as assertSchemaReferences, rt as RpcError, s as capabilityFreshAt, st as traceMessageTransport, t as createMemoryPrincipal, tn as schemaToZod, tt as withRpcTimeout, u as permits, ut as methodNameToTarget, v as InMemoryManagedIdentityStorage, vt as HUBRPC_SIGNATURE_KEY, w as KeypairIdentity, wt as readSignature, x as registerLazyIdentityOnOverlay, xt as LINKRPC_SIGNATURE_KEY, y as createManagedIdentity, yt as HUBRPC_UNSIGNED_KEY, z as ChannelConnector, zt as isNotification } from "./chunks/src-D3NUIwyo.js";
+import { n as hubFromConnection } from "./chunks/hubFacade-CQflVkVC.js";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { dirname } from "node:path";
+//#region src/node/ndjsonTransport.ts
+/**
+* Newline-delimited JSON transport over a Node Readable/Writable pair.
+* One JSON value per line, both directions.
+*
+* Not LSP-style headers — those add no value for a private link between two
+* cooperating processes and require a length-prefixed framer.
+*/
+var NdjsonTransport = class {
+	_input;
+	_output;
+	_onClose;
+	_listener;
+	_buffer = [];
+	_residual = "";
+	_closed = false;
+	constructor(_input, _output, _onClose) {
+		this._input = _input;
+		this._output = _output;
+		this._onClose = _onClose;
+		this._input.setEncoding?.("utf8");
+		this._input.on("data", (chunk) => this._onData(chunk));
+		this._input.on("end", () => this._onEnd());
+		this._input.on("close", () => this._onEnd());
+		this._input.on("error", () => this._onEnd());
+		if (!Object.is(this._output, this._input)) this._output.on("error", () => this._onEnd());
+	}
+	send(message) {
+		if (this._closed) return;
+		this._output.write(JSON.stringify(message) + "\n");
+	}
+	setListener(listener) {
+		this._listener = listener;
+		if (listener) while (this._buffer.length > 0 && this._listener) {
+			const m = this._buffer.shift();
+			this._listener(m);
+		}
+	}
+	dispose() {
+		if (this._closed) return;
+		this._closed = true;
+		this._onClose?.();
+	}
+	_onData(chunk) {
+		this._residual += chunk;
+		let nl;
+		while ((nl = this._residual.indexOf("\n")) >= 0) {
+			const line = this._residual.slice(0, nl).trim();
+			this._residual = this._residual.slice(nl + 1);
+			if (!line) continue;
+			let parsed;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			this._deliver(parsed);
+		}
+	}
+	_onEnd() {
+		if (!this._closed) {
+			this._closed = true;
+			this._onClose?.();
+		}
+	}
+	_deliver(m) {
+		if (this._listener) this._listener(m);
+		else this._buffer.push(m);
+	}
+};
+//#endregion
+//#region src/node/initialize.ts
+/**
+* Reserved transport-handshake method. Sent as the very first message on a
+* connection that authenticates and/or negotiates transport details. It is
+* handled entirely by the transport layer (via {@link connectNdjson}) and is
+* never forwarded to the hub or any service — it is not a routed call.
+*/
+const INITIALIZE_METHOD = "hubrpc::initialize";
+/** Transitional alias accepted by servers created during the LinkRPC wire-name migration. */
+const LINKRPC_INITIALIZE_METHOD_ALIAS = "linkrpc::initialize";
+/** Current transport protocol version. */
+const INITIALIZE_PROTOCOL_VERSION = 1;
+/** Default time (ms) to wait for the handshake message before giving up. */
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 1e4;
+/** Fixed request id for the initiator's `hubrpc::initialize` request. */
+const INITIALIZE_REQUEST_ID = 0;
+/**
+* The single supported way to build an ndjson transport. Constructs the
+* transport over `input`/`output` and, when {@link ConnectNdjsonOptions.initialize}
+* is set, runs the `hubrpc::initialize` handshake internally before resolving.
+*
+* Rejects (after disposing the transport) when the handshake fails — a bad or
+* missing token, a wrong/absent first message, or a timeout. The accepting side
+* should treat a rejection as "drop this connection".
+*/
+async function connectNdjson(opts) {
+	const role = opts.initialize;
+	let rejectClosedHandshake;
+	const closedDuringHandshake = role ? new Promise((_resolve, reject) => {
+		rejectClosedHandshake = reject;
+	}) : void 0;
+	const baseTransport = new NdjsonTransport(opts.input, opts.output, () => {
+		try {
+			opts.onClose?.();
+		} finally {
+			rejectClosedHandshake?.(/* @__PURE__ */ new Error("hubrpc::initialize: transport closed during handshake"));
+		}
+	});
+	const transport = opts.trace === void 0 ? baseTransport : traceMessageTransport(baseTransport, opts.trace);
+	if (!role) return { transport };
+	try {
+		const { token } = await Promise.race([runInitializeHandshake(transport, role, { ...opts.handshakeTimeoutMs !== void 0 ? { handshakeTimeoutMs: opts.handshakeTimeoutMs } : {} }), closedDuringHandshake]);
+		rejectClosedHandshake = void 0;
+		return {
+			transport,
+			...token !== void 0 ? { token } : {}
+		};
+	} catch (err) {
+		rejectClosedHandshake = void 0;
+		transport.dispose();
+		throw err;
+	}
+}
+/**
+* Run the `hubrpc::initialize` handshake on an already-constructed transport.
+* Used for transports that the caller builds itself (e.g. WebSocket), where
+* {@link connectNdjson} does not apply. On failure it throws but does NOT
+* dispose the transport — the caller owns it and decides how to tear down.
+*
+* For ndjson links, prefer {@link connectNdjson}, which constructs the
+* transport and runs this handshake atomically.
+*/
+async function runInitializeHandshake(transport, role, options = {}) {
+	const timeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+	if (role.kind === "client") {
+		await _runClientHandshake(transport, role.token, timeoutMs);
+		return {};
+	}
+	return { token: await _runServerHandshake(transport, role.isTokenAccepted, timeoutMs) };
+}
+async function _runClientHandshake(transport, token, timeoutMs) {
+	const reply = _nextMessage(transport, timeoutMs);
+	const params = {
+		protocolVersion: 1,
+		...token !== void 0 ? { token } : {}
+	};
+	transport.send({
+		jsonrpc: "2.0",
+		id: INITIALIZE_REQUEST_ID,
+		method: INITIALIZE_METHOD,
+		params
+	});
+	const message = await reply;
+	if (isRequest(message) || !("id" in message) || message.id !== INITIALIZE_REQUEST_ID) throw new Error("hubrpc::initialize: unexpected reply to handshake");
+	if ("error" in message) throw new Error(`hubrpc::initialize rejected: ${message.error.message}`);
+}
+async function _runServerHandshake(transport, isTokenAccepted, timeoutMs) {
+	const first = await _nextMessage(transport, timeoutMs);
+	if (!isRequest(first) || first.method !== "hubrpc::initialize" && first.method !== "linkrpc::initialize") throw new Error("hubrpc::initialize: expected initialize as the first message");
+	const params = first.params ?? {};
+	if (!await isTokenAccepted(params.token)) {
+		transport.send({
+			jsonrpc: "2.0",
+			id: first.id,
+			error: {
+				code: ErrorCode.invalidRequest,
+				message: "unauthenticated"
+			}
+		});
+		throw new Error("hubrpc::initialize: unauthenticated");
+	}
+	transport.send({
+		jsonrpc: "2.0",
+		id: first.id,
+		result: { protocolVersion: 1 }
+	});
+	return params.token;
+}
+/**
+* Consume exactly one incoming message, then detach. Relies on
+* {@link NdjsonTransport}'s buffering: setting the listener to `undefined` from
+* inside the callback stops the buffer drain, leaving any later messages queued
+* for the real listener the channel attaches afterwards.
+*/
+function _nextMessage(transport, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			transport.setListener(void 0);
+			reject(/* @__PURE__ */ new Error("hubrpc::initialize: handshake timed out"));
+		}, timeoutMs);
+		transport.setListener((message) => {
+			clearTimeout(timer);
+			transport.setListener(void 0);
+			resolve(message);
+		});
+	});
+}
+//#endregion
+//#region src/node/stdio.ts
+/**
+* Spawn a child process and connect to its stdio as a linkrpc connection.
+*
+* Pass a single command line (split on whitespace) or an array `[cmd, ...args]`.
+* The child's stderr is piped to the parent's stderr so logs surface naturally.
+*
+* @example
+*   const c = await connectToCmdStdio("node ./ghConnector.js");
+*   const gh = c.get(ghInterface);
+*   await gh.createIssue({ title: "..." });
+*/
+async function connectToCmdStdio(cmd) {
+	const parts = typeof cmd === "string" ? cmd.split(/\s+/).filter(Boolean) : [...cmd];
+	if (parts.length === 0) throw new Error("connectToCmdStdio: empty command");
+	const [bin, ...args] = parts;
+	const child = spawn(bin, args, { stdio: [
+		"pipe",
+		"pipe",
+		"inherit"
+	] });
+	if (!child.stdin || !child.stdout) throw new Error("connectToCmdStdio: child has no stdio");
+	const { transport } = await connectNdjson({
+		input: child.stdout,
+		output: child.stdin,
+		onClose: () => {
+			if (!child.killed) child.kill();
+		}
+	});
+	return LinkRpcConnection.fromTransport(transport);
+}
+/**
+* For the child side: a linkrpc connection over this process's stdin/stdout.
+* The child MUST NOT write user output to stdout — only RPC messages — or
+* the parent's parser will choke.
+*/
+async function serveOnStdio() {
+	const { transport } = await connectNdjson({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return LinkRpcConnection.fromTransport(transport);
+}
+async function openStdioChannel() {
+	const { transport } = await connectNdjson({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const channel = JsonRpcChannel.create(transport);
+	const closeListeners = /* @__PURE__ */ new Set();
+	let closed = false;
+	const fireClose = () => {
+		if (closed) return;
+		closed = true;
+		for (const l of closeListeners) try {
+			l();
+		} catch {}
+		closeListeners.clear();
+	};
+	process.stdin.on("end", fireClose);
+	process.stdin.on("close", fireClose);
+	return Object.assign(channel, { onClose: (listener) => {
+		if (closed) {
+			queueMicrotask(listener);
+			return { dispose: () => {} };
+		}
+		closeListeners.add(listener);
+		return { dispose: () => closeListeners.delete(listener) };
+	} });
+}
+//#endregion
+//#region src/node/webSocketClientTransport.ts
+/**
+* Client-side WebSocket transport: one JSON-RPC message per text frame.
+* Mirror of the hub's server-side `WebSocketTransport`, kept here so the
+* core node entry can reach a `ws://` / `wss://` hub without depending on
+* `@hediet/linkrpc-hub`.
+*
+* Uses the platform-global `WebSocket` (Node 22+, browsers), so no `ws`
+* package dependency is required on the client side.
+*
+* Takes ownership of the socket: {@link dispose} closes it, and a peer
+* close / error fires `onClose` exactly once.
+*/
+var WebSocketTransport = class {
+	_ws;
+	_onClose;
+	_listener;
+	_buffer = [];
+	_closed = false;
+	constructor(_ws, _onClose) {
+		this._ws = _ws;
+		this._onClose = _onClose;
+		_ws.binaryType = "arraybuffer";
+		_ws.addEventListener("message", (event) => {
+			const data = event.data;
+			const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? new TextDecoder().decode(data) : ArrayBuffer.isView(data) ? new TextDecoder().decode(data) : String(data);
+			for (const line of text.split("\n")) {
+				const trimmed = line.trim();
+				if (!trimmed) continue;
+				let parsed;
+				try {
+					parsed = JSON.parse(trimmed);
+				} catch {
+					continue;
+				}
+				this._deliver(parsed);
+			}
+		});
+		const onEnd = () => {
+			if (this._closed) return;
+			this._closed = true;
+			this._onClose?.();
+		};
+		_ws.addEventListener("close", onEnd);
+		_ws.addEventListener("error", onEnd);
+	}
+	send(message) {
+		if (this._closed) return;
+		if (this._ws.readyState !== WebSocket.OPEN) return;
+		this._ws.send(JSON.stringify(message));
+	}
+	setListener(listener) {
+		this._listener = listener;
+		if (listener) while (this._buffer.length > 0 && this._listener) {
+			const m = this._buffer.shift();
+			this._listener(m);
+		}
+	}
+	dispose() {
+		if (this._closed) return;
+		this._closed = true;
+		try {
+			this._ws.close();
+		} catch {}
+		this._onClose?.();
+	}
+	_deliver(m) {
+		if (this._listener) this._listener(m);
+		else this._buffer.push(m);
+	}
+};
+/**
+* Open a WebSocket to `url` and resolve once it is connected. Rejects if the
+* socket errors before open.
+*
+* Authentication is NOT done here: the hub's WebSocket server authenticates
+* over the in-band `hubrpc::initialize` handshake (so browsers, which cannot
+* set request headers on the `WebSocket` constructor, work too). Run
+* {@link runInitializeHandshake} on the resulting {@link WebSocketTransport}.
+*
+* Headers ride on the upgrade request via the non-standard `headers` option
+* supported by Node's global `WebSocket` (undici); browsers ignore it.
+*/
+function openWebSocket(url, opts = {}) {
+	const headers = { ...opts.headers };
+	return new Promise((resolve, reject) => {
+		const ws = new WebSocket(url, { headers });
+		const onOpen = () => {
+			ws.removeEventListener("error", onError);
+			resolve(ws);
+		};
+		const onError = (event) => {
+			ws.removeEventListener("open", onOpen);
+			const message = event.message;
+			reject(/* @__PURE__ */ new Error(message ? `WebSocket error: ${message}` : "WebSocket connection failed"));
+		};
+		ws.addEventListener("open", onOpen, { once: true });
+		ws.addEventListener("error", onError, { once: true });
+	});
+}
+//#endregion
+//#region src/node/hubClient.ts
+/** Env var the hub publishes for its endpoint (named pipe / UDS path). */
+const LINKRPC_ENDPOINT_VAR = "LINKRPC_ENDPOINT";
+/** Env var the hub publishes for its shared attribution token. */
+const LINKRPC_TOKEN_VAR = "LINKRPC_TOKEN";
+/**
+* Open a connection to a running linkrpc hub. Reads `LINKRPC_ENDPOINT` and
+* `LINKRPC_TOKEN` from the environment unless overridden. Sends the single-
+* line `{"hello":1,"token":"..."}` preamble that the hub's socket server
+* requires, then wraps the socket in an `LinkRpcConnection`.
+*
+* Throws if env vars are missing, if the socket cannot be opened, or if the
+* hub refuses the preamble (the socket simply closes — callers should treat
+* an immediate close of the channel as an auth failure).
+*/
+async function connectToHub(options = {}) {
+	const hubChannel = await openHubChannel(options);
+	const signing = {
+		principal: options.principal,
+		oneShotCaps: options.oneShotCaps
+	};
+	const channel = SigningSender.wrapChannel(hubChannel, signing);
+	const connection = new LinkRpcConnection(channel);
+	return {
+		connection,
+		hub: hubFromConnection(connection),
+		endpoint: hubChannel.endpoint,
+		token: hubChannel.token,
+		signing,
+		onClose: hubChannel.onClose,
+		close: () => {
+			connection.close();
+			hubChannel.close();
+		}
+	};
+}
+/**
+* Open the hub socket and send the preamble, returning the raw
+* {@link HubChannel} without any signing. Use this when you want to
+* compose identity yourself; otherwise prefer {@link connectToHub}.
+*/
+async function openHubChannel(options = {}) {
+	const endpoint = options.endpoint ?? process.env["LINKRPC_ENDPOINT"];
+	const token = options.token ?? process.env["LINKRPC_TOKEN"] ?? "";
+	if (!endpoint) throw new Error(`${LINKRPC_ENDPOINT_VAR} is not set; cannot connect to linkrpc hub.`);
+	const closeListeners = /* @__PURE__ */ new Set();
+	let closed = false;
+	let closeChannel;
+	const fireClose = () => {
+		if (closed) return;
+		closed = true;
+		closeChannel?.();
+		for (const l of closeListeners) try {
+			l();
+		} catch {}
+		closeListeners.clear();
+	};
+	const { transport, destroy } = await _openHubTransport(endpoint, token, fireClose);
+	const rpc = JsonRpcChannel.createWithClose(transport);
+	closeChannel = rpc.close;
+	if (closed) rpc.close();
+	return Object.assign(rpc.channel, {
+		endpoint,
+		token,
+		onClose: (listener) => {
+			if (closed) {
+				queueMicrotask(listener);
+				return { dispose: () => {} };
+			}
+			closeListeners.add(listener);
+			return { dispose: () => closeListeners.delete(listener) };
+		},
+		close: () => {
+			destroy();
+			fireClose();
+		}
+	});
+}
+/** True for `ws://` / `wss://` endpoints (case-insensitive). */
+function _isWebSocketEndpoint(endpoint) {
+	return /^wss?:\/\//i.test(endpoint);
+}
+/**
+* Open the underlying transport for {@link openHubChannel}, picking the
+* scheme from the endpoint:
+*  - `ws://` / `wss://` → WebSocket; the token is presented via the
+*    `hubrpc::initialize` handshake (browsers cannot set request headers).
+*  - anything else → named pipe / UDS; the token is presented via the
+*    `hubrpc::initialize` handshake the socket server requires.
+*
+* `onClose` fires once when the peer ends the transport.
+*/
+async function _openHubTransport(endpoint, token, onClose) {
+	if (_isWebSocketEndpoint(endpoint)) {
+		const ws = await openWebSocket(endpoint);
+		const transport = new WebSocketTransport(ws, onClose);
+		const destroy = () => {
+			try {
+				ws.close();
+			} catch {}
+		};
+		try {
+			await runInitializeHandshake(transport, {
+				kind: "client",
+				token
+			});
+		} catch (err) {
+			transport.dispose();
+			destroy();
+			throw err;
+		}
+		return {
+			transport,
+			destroy
+		};
+	}
+	const socket = await _openSocket(endpoint);
+	const { transport } = await connectNdjson({
+		input: socket,
+		output: socket,
+		onClose: () => {
+			socket.destroy();
+			onClose();
+		},
+		initialize: {
+			kind: "client",
+			token
+		}
+	});
+	return {
+		transport,
+		destroy: () => socket.destroy()
+	};
+}
+async function registerHubPrefix(opts) {
+	let params;
+	if (opts.identity) {
+		const signer = new KeypairSigningIdentity(opts.identity.principal, opts.identity.keypair.privateKey);
+		params = await signParams({
+			method: "hubServiceIdRegistry::registerServiceId",
+			params: { requestedPrefix: opts.prefix },
+			signingIdentity: signer,
+			...opts.capabilities && opts.capabilities.length > 0 ? { capabilities: [...opts.capabilities] } : {}
+		});
+	} else {
+		if (opts.capabilities && opts.capabilities.length > 0) throw new Error("registerHubPrefix: capabilities require identity to be set");
+		params = { requestedPrefix: opts.prefix };
+	}
+	await opts.handle.connection.channel.sendRequest("hubServiceIdRegistry::registerServiceId", params);
+}
+/**
+* Load the Ed25519 + X25519 keypairs for `id` from disk, or
+* generate-and-persist them on first call. The slot is keyed by SHA-256 of
+* `id` so callers can pass any stable string (e.g. `import.meta.filename`)
+* without worrying about filesystem-safe characters.
+*
+* Identity files written before wrapping support carried only the Ed25519
+* keypair; on load they are transparently migrated — the Ed25519 keypair
+* (and therefore the `nodeId`) is preserved and a fresh X25519 wrap keypair
+* is generated and written back.
+*
+* NOTE: keys are stored unencrypted. Only suitable for local development
+* identities — not for anything that must resist file-system attackers.
+*/
+async function loadOrCreateIdentity(opts) {
+	const file = opts.file ?? path.join(opts.storeDir ?? _defaultStoreDir(), `${_slotName(opts.id)}.json`);
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	try {
+		const raw = await fs.readFile(file, "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.privateKey !== "string" || typeof parsed.publicKey !== "string") throw new Error("malformed identity file");
+		const privateKey = base64UrlToBytes(parsed.privateKey);
+		const publicKey = base64UrlToBytes(parsed.publicKey);
+		const keypair = {
+			privateKey,
+			publicKey
+		};
+		let wrapKeypair;
+		if (typeof parsed.wrapPrivateKey === "string" && typeof parsed.wrapPublicKey === "string") wrapKeypair = {
+			privateKey: base64UrlToBytes(parsed.wrapPrivateKey),
+			publicKey: base64UrlToBytes(parsed.wrapPublicKey)
+		};
+		else {
+			wrapKeypair = await generateX25519Keypair();
+			await _writeIdentityFile(file, keypair, wrapKeypair, opts.id);
+		}
+		return {
+			keypair,
+			wrapKeypair,
+			principal: principalForPublicKey(publicKey),
+			file
+		};
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+	}
+	const keypair = await generateKeypair();
+	const wrapKeypair = await generateX25519Keypair();
+	await _writeIdentityFile(file, keypair, wrapKeypair, opts.id);
+	return {
+		keypair,
+		wrapKeypair,
+		principal: principalForPublicKey(keypair.publicKey),
+		file
+	};
+}
+async function _writeIdentityFile(file, keypair, wrapKeypair, id) {
+	const payload = {
+		privateKey: bytesToBase64Url(keypair.privateKey),
+		publicKey: bytesToBase64Url(keypair.publicKey),
+		wrapPrivateKey: bytesToBase64Url(wrapKeypair.privateKey),
+		wrapPublicKey: bytesToBase64Url(wrapKeypair.publicKey),
+		id
+	};
+	await fs.writeFile(file, JSON.stringify(payload, null, 2), { mode: 384 });
+}
+function _defaultStoreDir() {
+	const home = os.homedir();
+	if (process.platform === "win32") {
+		const appdata = process.env.APPDATA;
+		if (appdata) return path.join(appdata, "hubrpc", "identities");
+		return path.join(home, "AppData", "Roaming", "hubrpc", "identities");
+	}
+	if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "hubrpc", "identities");
+	const xdg = process.env.XDG_CONFIG_HOME;
+	if (xdg) return path.join(xdg, "hubrpc", "identities");
+	return path.join(home, ".config", "hubrpc", "identities");
+}
+function _slotName(id) {
+	const digest = sha256(new TextEncoder().encode(id));
+	let out = "";
+	for (let i = 0; i < 16; i++) out += digest[i].toString(16).padStart(2, "0");
+	return out;
+}
+async function loadPersistedRegisterCap(args) {
+	const file = _capFilePath(args.identityId, args.prefix, args.storeDir);
+	try {
+		const raw = await fs.readFile(file, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!parsed.capability) return void 0;
+		if (parsed.capability.expiresAtMs !== void 0 && parsed.capability.expiresAtMs < Date.now()) return;
+		return {
+			capability: parsed.capability,
+			file
+		};
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+		return;
+	}
+}
+async function persistRegisterCap(args) {
+	const file = _capFilePath(args.identityId, args.prefix, args.storeDir);
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	await fs.writeFile(file, JSON.stringify({ capability: args.capability }, null, 2), { mode: 384 });
+	return file;
+}
+function _capFilePath(identityId, prefix, storeDir) {
+	const dir = storeDir ?? _defaultStoreDir();
+	const slot = _slotName(identityId);
+	return path.join(dir, `${slot}-cap-${_slotName(prefix)}.json`);
+}
+function _openSocket(endpoint) {
+	return new Promise((resolve, reject) => {
+		const socket = net.createConnection(endpoint);
+		const onError = (err) => {
+			socket.removeListener("connect", onConnect);
+			reject(err);
+		};
+		const onConnect = () => {
+			socket.removeListener("error", onError);
+			resolve(socket);
+		};
+		socket.once("error", onError);
+		socket.once("connect", onConnect);
+	});
+}
+//#endregion
+//#region src/node/hubReconnect.ts
+/**
+* Connect to the hub, register `prefix`, run `setup`, and keep the
+* connection alive across hub restarts. When the socket closes, retries
+* with exponential backoff (re-reading `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN`
+* from `process.env` on each attempt so rotated tokens published by the
+* hub host get picked up if the parent shell re-exports them).
+*
+* The hub keeps recently-rotated tokens accepted for a grace window, so
+* even processes that captured the env at spawn time can usually reconnect
+* after a host reload without the parent re-exporting anything.
+*/
+function serveOverHubWithReconnect(options) {
+	const log = _makeLog(options.log, options.name ?? options.prefix);
+	const initial = options.initialBackoffMs ?? 200;
+	const max = options.maxBackoffMs ?? 5e3;
+	let stopped = false;
+	let current;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		current?.close();
+		current = void 0;
+	};
+	options.signal?.addEventListener("abort", stop, { once: true });
+	const claimer = options.identity ? createHubPrefixClaimer({
+		prefix: options.prefix,
+		identity: options.identity,
+		log
+	}) : void 0;
+	return {
+		stop,
+		done: (async () => {
+			let attempt = 0;
+			let backoff = initial;
+			while (!stopped) try {
+				if (attempt > 0) log(`reconnecting (attempt ${attempt + 1})…`);
+				const handle = await connectToHub();
+				current = handle;
+				if (claimer) await claimer.claim(handle);
+				else await registerHubPrefix({
+					handle,
+					prefix: options.prefix
+				});
+				await options.setup(handle.connection);
+				log(attempt === 0 ? `connected to hub at ${handle.endpoint} (prefix "${options.prefix}")` : `reconnected to hub (prefix "${options.prefix}")`);
+				attempt = 0;
+				backoff = initial;
+				await new Promise((resolve) => {
+					handle.onClose(() => resolve());
+				});
+				if (stopped) break;
+				log(`disconnected from hub`);
+				current = void 0;
+			} catch (err) {
+				if (stopped) break;
+				current?.close();
+				current = void 0;
+				const msg = err instanceof Error ? err.message : String(err);
+				log(`connect failed: ${msg}; retrying in ${backoff} ms`);
+				await _delay(backoff, options.signal);
+				attempt++;
+				backoff = Math.min(max, backoff * 2);
+			}
+		})()
+	};
+}
+/**
+* Build a reusable, stateful claimer for the signed register + capability
+* flow. Use this with {@link connectService}'s `reconnecting` connector to
+* claim a prefix on each (re)connect:
+*
+* ```ts
+* const claimer = createHubPrefixClaimer({ prefix, identity: { slot } });
+* connectService({
+*   connector: reconnecting(async () => {
+*     const handle = await connectToHub();
+*     try { await claimer.claim(handle); } catch (e) { handle.close(); throw e; }
+*     return handle;
+*   }),
+*   onConnect: ({ connection }) => registerService(connection),
+* });
+* ```
+*/
+function createHubPrefixClaimer(opts) {
+	const log = opts.log ?? (() => {});
+	let identity;
+	let cachedCap;
+	let capLoaded = false;
+	return { async claim(handle) {
+		if (!identity) {
+			const loaded = await loadOrCreateIdentity({
+				id: opts.identity.slot,
+				...opts.identity.storeDir !== void 0 ? { storeDir: opts.identity.storeDir } : {}
+			});
+			identity = {
+				principal: loaded.principal,
+				keypair: loaded.keypair
+			};
+		}
+		if (!capLoaded) {
+			cachedCap = (await loadPersistedRegisterCap({
+				identityId: opts.identity.slot,
+				prefix: opts.prefix,
+				...opts.identity.storeDir !== void 0 ? { storeDir: opts.identity.storeDir } : {}
+			}))?.capability;
+			capLoaded = true;
+		}
+		cachedCap = await _registerSigned(handle, opts.prefix, identity, cachedCap, opts.identity, log);
+	} };
+}
+const DEFAULT_ISSUER_METHOD = "hub-admin::hub-admin.capabilities::issueRegisterCap";
+/**
+* Try `registerHubPrefix` with `cachedCap`. On `permissionRequired`, call
+* the hub-admin issuer to mint a fresh cap, persist it, retry. Returns the
+* cap that actually worked (caller stores it for the next reconnect).
+*/
+async function _registerSigned(handle, prefix, identity, cachedCap, identityOpts, log) {
+	try {
+		await registerHubPrefix({
+			handle,
+			prefix,
+			identity,
+			...cachedCap ? { capabilities: [cachedCap] } : {}
+		});
+		return cachedCap;
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		if (!_isPermissionRequired(e) || identityOpts.issuerMethod === null) throw e;
+		log(`register denied (${msg}); requesting capability from hub-admin issuer…`);
+	}
+	const issuerMethod = identityOpts.issuerMethod ?? DEFAULT_ISSUER_METHOD;
+	const signer = new KeypairSigningIdentity(identity.principal, identity.keypair.privateKey);
+	const signedIssueParams = await signParams({
+		method: issuerMethod,
+		params: {
+			audience: identity.principal,
+			prefix,
+			...identityOpts.purpose !== void 0 ? { purpose: identityOpts.purpose } : {}
+		},
+		signingIdentity: signer
+	});
+	const issueResp = await handle.connection.channel.sendRequest(issuerMethod, signedIssueParams);
+	if (!issueResp?.capability) throw new Error("hub-admin issuer returned no capability");
+	const fresh = issueResp.capability;
+	await persistRegisterCap({
+		identityId: identityOpts.slot,
+		prefix,
+		capability: fresh,
+		...identityOpts.storeDir !== void 0 ? { storeDir: identityOpts.storeDir } : {}
+	});
+	await registerHubPrefix({
+		handle,
+		prefix,
+		identity,
+		capabilities: [fresh]
+	});
+	return fresh;
+}
+function _isPermissionRequired(e) {
+	if (e === null || typeof e !== "object") return false;
+	const rec = e;
+	if (typeof rec.code === "number") return rec.code === ErrorCode.permissionRequired;
+	const msg = e.message ?? "";
+	return /permission required/i.test(msg);
+}
+function _makeLog(sink, name) {
+	if (!sink) return () => {};
+	const write = sink === true ? (line) => {
+		process.stderr.write(line + "\n");
+	} : sink;
+	return (line) => write(`[linkrpc:${name}] ${line}`);
+}
+function _delay(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve();
+			return;
+		}
+		const t = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(t);
+			resolve();
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/node/fileManagedIdentityStorage.ts
+/**
+* A {@link ManagedIdentityStorage} backed by a single JSON file (one object
+* keyed by the storage keys). Suitable for self-managed identities that
+* persist their capability bag locally — e.g. pass it to `CapBag.load`.
+*
+* The file is created (mode 0o600) on first write; reads of a missing file
+* yield an empty store. Not concurrency-safe across processes.
+*/
+function fileManagedIdentityStorage(file) {
+	const read = async () => {
+		try {
+			return JSON.parse(await readFile(file, "utf8"));
+		} catch (e) {
+			if (e.code === "ENOENT") return {};
+			throw e;
+		}
+	};
+	const write = async (data) => {
+		await mkdir(dirname(file), { recursive: true });
+		await writeFile(file, JSON.stringify(data, null, 2), { mode: 384 });
+	};
+	return {
+		get: async (key) => (await read())[key],
+		set: async (key, value) => {
+			const data = await read();
+			data[key] = value;
+			await write(data);
+		},
+		delete: async (key) => {
+			const data = await read();
+			const existed = key in data;
+			delete data[key];
+			await write(data);
+			return existed;
+		},
+		list: async (prefix = "") => Object.keys(await read()).filter((k) => k.startsWith(prefix))
+	};
+}
+//#endregion
+//#region src/node/principal.ts
+/**
+* Self-managed principal: a local Ed25519 + X25519 keypair (created/loaded on
+* disk) signs and wraps/unwraps for outbound calls, and granted caps are
+* cached in a sibling file. Purely local — no transport needed — and
+* cheap/idempotent, so it can be re-derived on each reconnect. Used with
+* `--use-non-managed-identity`.
+*/
+async function createSelfManagedPrincipal(identityKey) {
+	return _selfManagedPrincipal({ id: identityKey });
+}
+/**
+* Self-managed principal whose keypair lives at an explicit file path (rather
+* than a slot derived from an id). Caps are cached in a sibling `.caps.json`.
+* Used by callers that want to pin the identity to a specific file, e.g. the
+* CLI's `--principal file:<path>`.
+*/
+async function createSelfManagedPrincipalFromFile(file) {
+	return _selfManagedPrincipal({
+		id: `file:${file}`,
+		file
+	});
+}
+async function _selfManagedPrincipal(opts) {
+	const id = await loadOrCreateIdentity({
+		id: opts.id,
+		file: opts.file
+	});
+	const capsFile = id.file.endsWith(".json") ? id.file.replace(/\.json$/, ".caps.json") : `${id.file}.caps.json`;
+	const capBag = await CapBag.load({ storage: fileManagedIdentityStorage(capsFile) });
+	const identity = new KeypairIdentity(id.principal, id.keypair.privateKey, id.wrapKeypair);
+	return new Principal(identity, capBag);
+}
+//#endregion
+//#region src/node/headerDelimitedTransport.ts
+const HEADER_SEPARATOR = Buffer.from("\r\n\r\n");
+const DEFAULT_MAX_HEADER_BYTES = 65536;
+const DEFAULT_MAX_CONTENT_LENGTH = 67108864;
+const DEFAULT_MAX_PENDING_MESSAGES = 1024;
+/**
+* LSP "base protocol" framing over a Node Readable/Writable pair.
+*
+* The streams remain owned by the caller: close/dispose detach listeners but
+* never end, destroy, or otherwise take ownership of either stream.
+*/
+var HeaderDelimitedTransport = class {
+	_input;
+	_output;
+	_onClose;
+	_listener;
+	_pending = [];
+	_residual = Buffer.alloc(0);
+	_expectedLength;
+	_closed = false;
+	_closeReason;
+	_maxHeaderBytes;
+	_maxContentLength;
+	_maxPendingMessages;
+	_onDataListener = (chunk) => this._onData(chunk);
+	_onEndListener = () => this._onEnd();
+	_onInputErrorListener = (error) => this.close(`Header-delimited input error: ${error.message}`);
+	_onOutputErrorListener = (error) => this.close(`Header-delimited output error: ${error.message}`);
+	constructor(_input, _output, _onClose, options = {}) {
+		this._input = _input;
+		this._output = _output;
+		this._onClose = _onClose;
+		this._maxHeaderBytes = positiveLimit(options.maxHeaderBytes, DEFAULT_MAX_HEADER_BYTES, "maxHeaderBytes");
+		this._maxContentLength = positiveLimit(options.maxContentLength, DEFAULT_MAX_CONTENT_LENGTH, "maxContentLength");
+		this._maxPendingMessages = positiveLimit(options.maxPendingMessages, DEFAULT_MAX_PENDING_MESSAGES, "maxPendingMessages");
+		_input.on("data", this._onDataListener);
+		_input.on("end", this._onEndListener);
+		_input.on("close", this._onEndListener);
+		_input.on("error", this._onInputErrorListener);
+		_output.on("error", this._onOutputErrorListener);
+	}
+	get closed() {
+		return this._closed;
+	}
+	get closeReason() {
+		return this._closeReason;
+	}
+	send(message) {
+		if (this._closed) return Promise.reject(new Error(this._closeReason ?? "Header-delimited transport is closed"));
+		const body = Buffer.from(JSON.stringify(message), "utf8");
+		if (body.length > this._maxContentLength) return Promise.reject(/* @__PURE__ */ new Error(`Header-delimited payload exceeds ${this._maxContentLength} bytes`));
+		const wire = Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii"), body]);
+		return new Promise((resolve, reject) => {
+			this._output.write(wire, (error) => {
+				if (error) reject(error);
+				else resolve();
+			});
+		});
+	}
+	setListener(listener) {
+		this._listener = listener;
+		while (this._listener && this._pending.length > 0) this._listener(this._pending.shift());
+	}
+	dispose() {
+		this.close("Header-delimited transport disposed");
+	}
+	close(reason = "Header-delimited transport closed") {
+		if (this._closed) return;
+		this._closed = true;
+		this._closeReason = reason;
+		this._input.off("data", this._onDataListener);
+		this._input.off("end", this._onEndListener);
+		this._input.off("close", this._onEndListener);
+		this._input.off("error", this._onInputErrorListener);
+		this._output.off("error", this._onOutputErrorListener);
+		this._onClose?.(reason);
+	}
+	_onData(chunk) {
+		if (this._closed) return;
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+		this._residual = this._residual.length === 0 ? Buffer.from(bytes) : Buffer.concat([this._residual, bytes]);
+		while (!this._closed) {
+			if (this._expectedLength === void 0) {
+				const headerEnd = this._residual.indexOf(HEADER_SEPARATOR);
+				if (headerEnd < 0) {
+					if (this._residual.length > this._maxHeaderBytes) this.close(`Invalid header-delimited frame: header exceeds ${this._maxHeaderBytes} bytes`);
+					return;
+				}
+				if (headerEnd + HEADER_SEPARATOR.length > this._maxHeaderBytes) {
+					this.close(`Invalid header-delimited frame: header exceeds ${this._maxHeaderBytes} bytes`);
+					return;
+				}
+				try {
+					this._expectedLength = parseHeaders(this._residual.subarray(0, headerEnd), this._maxContentLength);
+				} catch (error) {
+					this.close(`Invalid header-delimited frame: ${error instanceof Error ? error.message : String(error)}`);
+					return;
+				}
+				this._residual = this._residual.subarray(headerEnd + HEADER_SEPARATOR.length);
+			}
+			if (this._residual.length < this._expectedLength) return;
+			const body = this._residual.subarray(0, this._expectedLength);
+			this._residual = this._residual.subarray(this._expectedLength);
+			this._expectedLength = void 0;
+			let parsed;
+			try {
+				parsed = JSON.parse(body.toString("utf8"));
+			} catch (error) {
+				this.close(`Invalid header-delimited JSON payload: ${error instanceof Error ? error.message : String(error)}`);
+				return;
+			}
+			this._deliver(parsed);
+		}
+	}
+	_onEnd() {
+		if (this._closed) return;
+		this.close(this._expectedLength !== void 0 || this._residual.length > 0 ? "Truncated header-delimited frame" : "Header-delimited input closed");
+	}
+	_deliver(message) {
+		if (this._listener) {
+			this._listener(message);
+			return;
+		}
+		if (this._pending.length >= this._maxPendingMessages) {
+			this.close(`Header-delimited pending message limit ${this._maxPendingMessages} exceeded`);
+			return;
+		}
+		this._pending.push(message);
+	}
+};
+function parseHeaders(headerBytes, maxContentLength) {
+	const values = /* @__PURE__ */ new Map();
+	for (const line of headerBytes.toString("ascii").split("\r\n")) {
+		const colon = line.indexOf(":");
+		if (colon <= 0) throw new Error(`malformed header ${JSON.stringify(line)}`);
+		const name = line.slice(0, colon).trim().toLowerCase();
+		const value = line.slice(colon + 1).trim();
+		if (values.has(name)) throw new Error(`duplicate ${name} header`);
+		values.set(name, value);
+	}
+	const rawLength = values.get("content-length");
+	if (rawLength === void 0 || !/^(0|[1-9]\d*)$/.test(rawLength)) throw new Error("missing or invalid Content-Length header");
+	const length = Number(rawLength);
+	if (!Number.isSafeInteger(length) || length > maxContentLength) throw new Error(`Content-Length exceeds ${maxContentLength} bytes`);
+	const contentType = values.get("content-type");
+	if (contentType !== void 0 && !isSupportedContentType(contentType)) throw new Error(`unsupported Content-Type ${JSON.stringify(contentType)}`);
+	return length;
+}
+function isSupportedContentType(value) {
+	const parts = value.split(";").map((part) => part.trim().toLowerCase());
+	return parts[0] === "application/vscode-jsonrpc" && parts.slice(1).every((part) => /^charset\s*=\s*"?utf-?8"?$/.test(part));
+}
+function positiveLimit(value, fallback, name) {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result <= 0) throw new Error(`${name} must be a positive integer`);
+	return result;
+}
+//#endregion
+export { CapBag, Channel, ChannelConnector, DEFAULT_RPC_TIMEOUT_MS, EXTENSION_PREFIX, ErrorCode, HUBRPC_META_KEY, HUBRPC_SIGNATURE_KEY, HUBRPC_UNSIGNED_KEY, HeaderDelimitedTransport, INITIALIZE_METHOD, INITIALIZE_PROTOCOL_VERSION, InMemoryManagedIdentity, InMemoryManagedIdentityStorage, InterfaceDefinition, JsonRpcChannel, KEY_ID_PREFIX, KeypairIdentity, KeypairSigningIdentity, LINKRPC_ENDPOINT_VAR, LINKRPC_INITIALIZE_METHOD_ALIAS, LINKRPC_META_KEY, LINKRPC_SIGNATURE_KEY, LINKRPC_TOKEN_VAR, LINKRPC_UNSIGNED_KEY, LinkRpcConnection, MultiplexedTransport, NotificationType, OneShotCapStaging, PRINCIPAL_PREFIX, Principal, PrincipalWithStore, PublicSigningIdentity, PublicWrappingIdentity, RequestType, RpcError, STREAM_METHOD, ServiceHandle, SigningSender, StreamControlReason, StreamControlType, StreamDir, TransportPair, WebSocketTransport, assertSchemaReferences, attachCapabilities, bareInterfaceTarget, base64UrlToBytes, bytesToBase64Url, capBagFreshAt, capabilityFreshAt, capabilityPermits, componentSchemaName, componentSchemaRef, computeInterfaceHash, connectNdjson, connectToCmdStdio, connectToHub, connectTransports, createHubPrefixClaimer, createManagedIdentity, createManagedPrincipal, createMemoryPrincipal, createSchemaToZod, createSeededMemoryPrincipal, createSeededSigningIdentity, createSelfManagedPrincipal, createSelfManagedPrincipalFromFile, crypto_exports as crypto, defaultsInterface, defineInterface, directoryInterface, directoryWatchNever, fileManagedIdentityStorage, formatEndpointUri, generateTsInterface, getKeyId, hasSignedCapabilityShape, identityInterface, identityStorageInterface, interfaceFromSchema, invoke, isAssignable, isHubEndpoint, isNotification, isRequest, isResponse, issueCapability, jcsCanonicalize, jcsCanonicalizeBytes, keyIdForPrincipal, keyIdForPublicKey, loadOrCreateIdentity, matchParams, materializeJsonSchema, methodNameToTarget, nodeInterface, normalizeJsonSchema, notificationType, openHubChannel, openStdioChannel, openWebSocket, parseEndpointUri, parseMethodName, permissionMatchesTarget, permissionPermits, permits, prefix, principalForPublicKey, publicKeyForKeyId, readSignature, registerHubPrefix, registerIdentityOnOverlay, registerLazyIdentityOnOverlay, requestType, requireObjectParams, resolveSigningKey, runInitializeHandshake, schemaToZod, schemasInterface, serveOnStdio, serveOverHubWithReconnect, signCapability, signParams, signRpcCall, signedHash, signingDomainValue, signingInput, streamInterface, stripLinkRpcWireMeta, topologyInterface, traceMessageTransport, trafficInterface, verifyCall, verifyRpcCall, withRpcTimeout, withSignature, zParticipantDescriptor, zParticipantDescriptorSource, zRouteClaim, zServiceIdPattern, zTopologyGraph, zTopologyLink, zTopologyLinkEndpoint, zTopologyNode, zTopologyPort, zTopologyTransportEndpoint, zTopologyTransportInfo, zTrafficEvent, zTrafficOverflowEvent, zTrafficTransitEndpoint, zTrafficTransitEvent, zTrafficWatchResult, zodToSvcJsonSchema };
+
+//# sourceMappingURL=node.js.map