@hediet/linkrpc 0.0.1

package/dist/node.d.ts

@@ -0,0 +1,548 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { $ as ManagedIdentityStorageBackend, $i as DiscriminatorSchema, $n as signedHash, $r as zTopologyLinkEndpoint, $t as Result, A as VerifyRpcCallResult, Ai as InterfaceMemberRefMap, An as Capability, Ar as nodeInterface, At as WsNoInitEndpoint, B as OneShotCapStaging, Bi as RequestType, Bn as permissionPermits, Br as TopologyTransportInfo, Bt as ExpBackoffOptions, C as VerifyCallOptions, Ca as JsonValue, Ci as computeInterfaceHash, Cn as ParsedMethodName, Cr as StreamControlReason, Ct as CmdEnvEndpoint, D as SignRpcCallOptions, Di as InterfaceHandlers, Dn as Call, Dr as streamInterface, Dt as ResolvedEndpoint, E as verifyCall, Ei as InterfaceDefinitionOpts, En as Ability, Er as StreamSendParams, Et as FormatEndpointOptions, F as identityStorageInterface, Fi as defineInterface, Fn as TargetPattern, Fr as TopologyLink, Ft as DEFAULT_RPC_TIMEOUT_MS, G as createManagedPrincipal, Gi as zodToSvcJsonSchema, Gn as LINKRPC_META_KEY, Gr as TrafficWatchResult, Gt as Channel, H as SigningSender, Hi as ZodToSvcJsonSchemaOptions, Hn as HUBRPC_META_KEY, Hr as TrafficOverflowEvent, Ht as OnChannelConnect, I as crypto_d_exports, Ii as interfaceFromSchema, In as capabilityPermits, Ir as TopologyLinkEndpoint, It as withRpcTimeout, J as CapBagOptions, Ji as MemberAnnotations, Jn as SignDomain, Jr as zParticipantDescriptor, Jt as IRequestSender, K as Principal, Ki as ErrorSchema, Kn as LINKRPC_SIGNATURE_KEY, Kr as topologyInterface, Kt as ChannelTransport, L as CapProvider, Li as MemberDocs, Ln as hasSignedCapabilityShape, Lr as TopologyNode, Lt as JsonRpcChannel, M as signRpcCall, Mi as StreamApi, Mn as Pattern, Mr as ParticipantDescriptorSource, Mt as isHubEndpoint, N as verifyRpcCall, Ni as StreamCallOptions, Nn as Permission, Nr as RouteClaim, Nt as parseEndpointUri, O as SignedRpcCall, Oi as InterfaceInfo, On as CallBind, Or as NodeInfo, Ot as SocketEndpoint, P as identityInterface, Pi as StreamingCall, Pn as SignedCapability, Pr as TopologyGraph, Pt as CancellableRequest, Q as ManagedIdentityStorage, Qi as ConstSchema, Qn as readSignature, Qr as zTopologyLink, Qt as RawStreamingCall, R as CapProviderResult, Ri as MemberType, Rn as matchParams, Rr as TopologyPort, Rt as ChannelConnector, S as SignParamsOptions, Sa as isResponse, Si as EXTENSION_PREFIX, Sn as stripLinkRpcWireMeta, Sr as STREAM_METHOD, St as WrappingIdentity, T as signParams, Ti as InterfaceDefinition, Tn as parseMethodName, Tr as StreamDir, Tt as EndpointCommand, U as SigningSenderConfig, Ui as notificationType, Un as HUBRPC_SIGNATURE_KEY, Ur as TrafficTransitEndpoint, Ut as BareInterfaceTarget, V as SigningCallCtx, Vi as Schema, Vn as Base64Sha256, Vr as TrafficEvent, Vt as KeepConnectedHandle, W as PrincipalWithStore, Wi as requestType, Wn as HUBRPC_UNSIGNED_KEY, Wr as TrafficTransitEvent, Wt as bareInterfaceTarget, X as InMemoryManagedIdentityStorage, Xi as ArraySchema, Xn as Signatures, Xr as zRouteClaim, Xt as IncomingStream, Y as InMemoryManagedIdentity, Yi as MethodSchema, Yn as SignatureEnvelope, Yr as zParticipantDescriptorSource, Yt as IncomingCall, Z as ManagedIdentity, Zi as BooleanSchema, Zn as getKeyId, Zr as zTopologyGraph, Zt as MessageWithCtx, _ as SeededPrincipalOptions, _a as JsonRpcResponse, _i as componentSchemaName, _n as LinkRpcJsonRpcRequest, _r as principalForPublicKey, _t as KeypairSigningIdentity, a as LinkRpcConnection, aa as ObjectSchema, ai as zTrafficOverflowEvent, an as IMessageTransport, ar as Keypair, at as ParamMatcherFor, b as createSeededSigningIdentity, ba as isNotification, bi as isAssignable, bn as LinkRpcWireParams, br as jcsCanonicalize, bt as SerializedKeypairSigningIdentity, c as ServiceHandle, ca as SchemaBase, ci as zTrafficWatchResult, cn as MessageTransportWithContext, cr as PrivateKey, ct as capBagFreshAt, d as ServiceIdPattern, da as UnionSchema, di as SchemaToZodContext, dn as connectTransports, dr as Signature, dt as issueCapability, ea as EnumSchema, ei as zTopologyNode, en as RpcError, er as signingDomainValue, et as createManagedIdentity, f as defaultsInterface, fa as ErrorCode, fi as createSchemaToZod, fn as traceMessageTransport, fr as X25519Keypair, ft as permits, g as zServiceIdPattern, ga as JsonRpcRequest, gi as assertSchemaReferences, gn as LinkRpcJsonRpcNotification, gr as keyIdForPublicKey, gt as KeypairIdentity, h as schemasInterface, ha as JsonRpcNotification, hi as materializeJsonSchema, hn as LinkRpcJsonRpcMessage, hr as keyIdForPrincipal, ht as Identity, i as InterfaceRegistration, ia as NumberSchema, ii as zTrafficEvent, in as MuxEnvelope, ir as KeyId, it as IssueCapabilityOptions, j as attachCapabilities, ji as MemberMap, jn as ParamMatcher, jr as ParticipantDescriptor, jt as formatEndpointUri, k as VerifyRpcCallOptions, ki as InterfaceMemberRef, kn as CallTarget, kr as TopologyIdGenerator, kt as WsEndpoint, l as RootPrincipalReq, la as StringSchema, li as GenerateInterfaceOptions, ln as MessageWithContext, lr as PublicKey, lt as capabilityFreshAt, m as directoryWatchNever, ma as JsonRpcMessage, mi as MaterializedJsonSchema, mn as CallMeta, mr as bytesToBase64Url, mt as signCapability, n as GetOptions, na as LinkRpcJsonSchema, ni as zTopologyTransportEndpoint, nn as StreamSendOpts, nr as withSignature, nt as registerLazyIdentityOnOverlay, o as LinkRpcConnectionOptions, oa as OneOfSchema, oi as zTrafficTransitEndpoint, on as MessageTransportDirection, or as PRINCIPAL_PREFIX, ot as ParamMatchers, p as directoryInterface, pa as JsonRpcError, pi as schemaToZod, pn as IDisposable, pr as base64UrlToBytes, pt as prefix, q as CapBag, qi as LinkRpcInterfaceSchema, qn as LINKRPC_UNSIGNED_KEY, qr as trafficInterface, qt as IRequestHandler, r as InspectionRegistration, ra as NullSchema, ri as zTopologyTransportInfo, rn as MultiplexedTransport, rr as KEY_ID_PREFIX, rt as AcceptedRootIssuer, s as RegisterOptions, sa as RefSchema, si as zTrafficTransitEvent, sn as MessageTransportTrace, sr as PrincipalId, st as PermitResult, t as BareGetOptions, ta as IntegerSchema, ti as zTopologyPort, tn as SendOpts, tr as signingInput, tt as registerIdentityOnOverlay, u as RootPrincipalSet, ua as TupleSchema, ui as generateTsInterface, un as TransportPair, ur as ResolveSigningKeyArgs, ut as invoke, v as createMemoryPrincipal, va as JsonRpcSuccess, vi as componentSchemaRef, vn as LinkRpcUnsigned, vr as publicKeyForKeyId, vt as PublicSigningIdentity, w as VerifyResult, wi as InterfaceClient, wn as methodNameToTarget, wr as StreamControlType, wt as CmdStdioEndpoint, x as JsonObject, xa as isRequest, xi as normalizeJsonSchema, xn as requireObjectParams, xr as jcsCanonicalizeBytes, xt as SigningIdentity, y as createSeededMemoryPrincipal, ya as RequestId, yi as Components, yn as LinkRpcWireMeta, yr as resolveSigningKey, yt as PublicWrappingIdentity, z as ManagedSigningChannel, zi as NotificationType, zn as permissionMatchesTarget, zr as TopologyTransportEndpoint, zt as ConnectableChannel } from "./chunks/linkRpcConnection-CtlQmetO.js";
+import { t as Hub } from "./chunks/hubFacade-Dkgw2pTi.js";
+//#region src/node/stdio.d.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: "..." });
+ */
+declare function connectToCmdStdio(cmd: string | readonly string[]): Promise<LinkRpcConnection>;
+/**
+ * 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.
+ */
+declare function serveOnStdio(): Promise<LinkRpcConnection>;
+/**
+ * A raw, unsigned channel over this process's stdin/stdout — the stdio
+ * counterpart to `openHubChannel`. It *is* a {@link Channel} (so it plugs
+ * straight into {@link SigningSender.wrapChannel} / `new LinkRpcConnection`),
+ * augmented with a close signal for stdin end. Use {@link serveOnStdio}
+ * instead when no signing is needed.
+ */
+type StdioChannel = Channel<undefined, unknown> & {
+  /** Fires once when stdin ends/closes. Returns a disposable to unsubscribe. */
+  onClose(listener: () => void): IDisposable;
+};
+declare function openStdioChannel(): Promise<StdioChannel>;
+//#endregion
+//#region src/node/hubClient.d.ts
+/** Env var the hub publishes for its endpoint (named pipe / UDS path). */
+declare const LINKRPC_ENDPOINT_VAR = "LINKRPC_ENDPOINT";
+/** Env var the hub publishes for its shared attribution token. */
+declare const LINKRPC_TOKEN_VAR = "LINKRPC_TOKEN";
+interface ConnectToHubOptions {
+  /** Defaults to `process.env.LINKRPC_ENDPOINT`. */
+  readonly endpoint?: string;
+  /** Defaults to `process.env.LINKRPC_TOKEN`. */
+  readonly token?: string;
+  /**
+   * Initial {@link Principal} (identity + persistent caps) for outbound
+   * calls. Stored on the returned handle's {@link HubClientHandle.signing}
+   * config; mutate that later to install or swap. `undefined` leaves the
+   * connection unsigned (plain JSON-RPC) until a principal is installed.
+   */
+  readonly principal?: Principal;
+  /**
+   * Initial one-shot capability staging policy. Same lifecycle as
+   * {@link principal}; drained per outbound signed call.
+   */
+  readonly oneShotCaps?: OneShotCapStaging;
+}
+/**
+ * Mutable signing config consulted per-call by the {@link SigningSender}
+ * wrapping a {@link HubClientHandle.connection}. Mutating either field
+ * takes effect on the next outbound call. No setter on the sender
+ * itself — it is a plain caller-owned {@link SigningSenderConfig}.
+ */
+type HubSigningHolder = {
+  principal?: Principal;
+  capProvider?: SigningSenderConfig['capProvider'];
+  oneShotCaps?: OneShotCapStaging;
+};
+interface HubClientHandle {
+  /** Full linkrpc connection wrapping the same transport. */
+  readonly connection: LinkRpcConnection<undefined, SigningCallCtx>;
+  /**
+   * Façade over the hub's own serviceId-routed services (`hubGrantedServiceId`,
+   * `hubAccess`, …) on this {@link connection}. Use it to read connection
+   * facts ({@link Hub.getConnectionInfo}) or claim this connection's granted
+   * serviceId namespace ({@link Hub.claimGrantedServiceIdNamespace}) without
+   * hand-routing the interface clients.
+   */
+  readonly hub: Hub;
+  /** Configured endpoint + token (in case the caller defaulted from env). */
+  readonly endpoint: string;
+  readonly token: string;
+  /**
+   * Mutable signing config. Starts empty (every call goes out
+   * unsigned). `installManagedIdentitySigner` and `setupHubSigning`
+   * populate this; user code can also drive it directly.
+   */
+  readonly signing: HubSigningHolder;
+  /**
+   * Register a callback that fires when the underlying socket closes
+   * (peer end, error, or explicit {@link close}). Fires at most once.
+   * Returns an unsubscribe function.
+   */
+  onClose(listener: () => void): IDisposable;
+  /** Close the underlying socket and tear everything down. */
+  close(): void;
+}
+/**
+ * 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).
+ */
+declare function connectToHub(options?: ConnectToHubOptions): Promise<HubClientHandle>;
+/** Options for {@link openHubChannel}. Subset of {@link ConnectToHubOptions}. */
+interface OpenHubChannelOptions {
+  /** Defaults to `process.env.LINKRPC_ENDPOINT`. */
+  readonly endpoint?: string;
+  /**
+   * Defaults to `process.env.LINKRPC_TOKEN`, or `''` when unset. The token
+   * is sent in the hello preamble; provenance-authenticated hubs (hubv2)
+   * ignore it, so an empty token is valid there.
+   */
+  readonly token?: string;
+}
+/**
+ * A raw, unsigned hub channel: the socket transport wrapped only in a
+ * {@link JsonRpcChannel}, with no signing applied. It *is* a {@link Channel}
+ * (so it plugs straight into {@link SigningSender.wrapChannel} /
+ * `new LinkRpcConnection`), augmented with the hub endpoint/token and the
+ * socket lifecycle. Identity/signing is composed on top by the caller;
+ * {@link connectToHub} is the batteries-included version that adds a
+ * mutable signing holder.
+ */
+type HubChannel = Channel<undefined, unknown> & {
+  readonly endpoint: string;
+  readonly token: string;
+  /**
+   * Register a callback that fires when the socket closes. Fires at most
+   * once. Returns an unsubscribe function.
+   */
+  onClose(listener: () => void): IDisposable;
+  /** Close the underlying socket. */
+  close(): void;
+};
+/**
+ * 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}.
+ */
+declare function openHubChannel(options?: OpenHubChannelOptions): Promise<HubChannel>;
+/**
+ * Send the `linkrpc.hub::hubServiceIdRegistry::registerServiceId` call on an open
+ * hub connection. In `openMode` the hub accepts the unsigned call directly —
+ * pass no `identity`. Outside `openMode` the caller must sign the params
+ * with their `identity` keypair (via `signParams`) and present a
+ * capability that authorizes the claim — unless the signer is already an
+ * admin on the hub, in which case `capabilities` may be omitted.
+ *
+ * Resolves once the hub has registered the prefix; rejects on denial.
+ */
+interface RegisterHubPrefixOptions {
+  readonly handle: HubClientHandle;
+  readonly prefix: string;
+  /**
+   * Caller's signing identity. Required when the hub is not in openMode.
+   * The `principal` must encode the `publicKey` (round-tripped through
+   * `principalForPublicKey`). Bound to this transport on first successful
+   * `register` — subsequent calls on the same socket may not switch
+   * identity.
+   */
+  readonly identity?: {
+    readonly principal: PrincipalId;
+    readonly keypair: Keypair;
+  };
+  /**
+   * Capabilities to present. Each must be issued (directly or
+   * transitively) by an admin and permit
+   * `<prefix>::hubServiceIdRegistry::registerServiceId`. Omit when the signer
+   * is already an admin.
+   */
+  readonly capabilities?: readonly SignedCapability[];
+}
+declare function registerHubPrefix(opts: RegisterHubPrefixOptions): Promise<void>;
+interface LoadOrCreateIdentityOptions {
+  /**
+   * Stable string that identifies this identity slot. Typically the calling
+   * module's `import.meta.filename` — each service then automatically gets
+   * its own slot.
+   */
+  readonly id: string;
+  /** Override the storage directory (defaults to a per-user folder). */
+  readonly storeDir?: string;
+  /**
+   * Use this exact on-disk path for the keypair file instead of deriving one
+   * from `id` (and `storeDir`). Takes precedence over `storeDir`; the parent
+   * directory is created if missing.
+   */
+  readonly file?: string;
+}
+interface PersistedIdentity {
+  readonly principal: PrincipalId;
+  readonly keypair: Keypair;
+  /** Long-lived X25519 keypair used for HPKE wrap/unwrap. */
+  readonly wrapKeypair: X25519Keypair;
+  /** Absolute path of the on-disk file. */
+  readonly file: string;
+}
+/**
+ * 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.
+ */
+declare function loadOrCreateIdentity(opts: LoadOrCreateIdentityOptions): Promise<PersistedIdentity>;
+//#endregion
+//#region src/node/hubReconnect.d.ts
+interface ServeOverHubIdentityOptions {
+  /**
+   * Stable slot id for the on-disk keypair. Typically the caller's
+   * `import.meta.filename`. Same id always loads the same keypair, so
+   * persistent capabilities keep working across runs.
+   */
+  readonly slot: string;
+  /**
+   * Override the on-disk identity / capability store directory (defaults
+   * to a per-user folder, see `loadOrCreateIdentity`).
+   */
+  readonly storeDir?: string;
+  /**
+   * Override the form-3 method the helper uses to request a register
+   * capability when the hub rejects an unsigned / un-capped register.
+   * Defaults to
+   * `hub-admin::hub-admin.capabilities::issueRegisterCap`. Setting this
+   * to `null` disables the fallback (the helper just propagates the
+   * `permissionRequired` error).
+   */
+  readonly issuerMethod?: string | null;
+  /**
+   * Optional human-friendly purpose string passed to the issuer service.
+   * Surfaced in the user-facing approval prompt.
+   */
+  readonly purpose?: string;
+}
+interface ServeOverHubOptions {
+  /** Service prefix to register with the hub. */
+  readonly prefix: string;
+  /**
+   * Wires handlers onto the connection (registers interfaces, enables
+   * reflection, etc). Called once per successful connection attempt,
+   * after the prefix has been registered. Must not retain references to
+   * the connection across calls — a fresh connection is passed every
+   * reconnect.
+   */
+  readonly setup: (connection: LinkRpcConnection<undefined, SigningCallCtx>) => void | Promise<void>;
+  /**
+   * Optional human-readable name used in log lines (defaults to `prefix`).
+   */
+  readonly name?: string;
+  /** When set, prints connect/disconnect/retry lines to this sink. */
+  readonly log?: ((line: string) => void) | true;
+  /**
+   * Initial retry delay in ms (capped doubling on each consecutive
+   * failure). Defaults to 200 ms.
+   */
+  readonly initialBackoffMs?: number;
+  /** Cap on backoff in ms. Defaults to 5000 ms. */
+  readonly maxBackoffMs?: number;
+  /**
+   * Abort the loop. When the signal is aborted, the current handle is
+   * closed and the loop exits. The returned promise resolves once the
+   * loop has finished.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * When set, registration is performed against a secure-mode hub: the
+   * caller's `$hubrpc`-signed `hubServiceIdRegistry::registerServiceId` carries a
+   * presented capability. The first attempt loads any cached cap from
+   * disk; on `permissionRequired` the helper calls the hub-admin issuer
+   * service to obtain a fresh cap, persists it, and retries. Subsequent
+   * reconnects reuse the cached cap. Omit to use the legacy unsigned
+   * path (only works against an openMode hub).
+   */
+  readonly identity?: ServeOverHubIdentityOptions;
+}
+interface ServeOverHubController {
+  /** Stops the loop and closes the current handle, if any. */
+  stop(): void;
+  /**
+   * Resolves when the loop exits (signal aborted or `stop()` called).
+   * Rejects only on programmer errors thrown by `setup`.
+   */
+  readonly done: Promise<void>;
+}
+/**
+ * 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.
+ */
+declare function serveOverHubWithReconnect(options: ServeOverHubOptions): ServeOverHubController;
+interface HubPrefixClaimerOptions {
+  /** Service prefix to register with the hub. */
+  readonly prefix: string;
+  /** Identity + capability-issuance options (see {@link ServeOverHubIdentityOptions}). */
+  readonly identity: ServeOverHubIdentityOptions;
+  /** When set, prints register/capability lines to this sink. */
+  readonly log?: (line: string) => void;
+}
+interface HubPrefixClaimer {
+  /**
+   * Register the configured prefix on `handle`'s hub, performing the
+   * `$hubrpc`-signed register plus capability dance: presents the cached
+   * cap, and on `permissionRequired` mints a fresh one via the hub-admin
+   * issuer, persists it, and retries. Call once per (re)connect, before
+   * serving handlers. The loaded identity and cap are cached across calls.
+   */
+  claim(handle: HubClientHandle): Promise<void>;
+}
+/**
+ * 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),
+ * });
+ * ```
+ */
+declare function createHubPrefixClaimer(opts: HubPrefixClaimerOptions): HubPrefixClaimer;
+//#endregion
+//#region src/node/fileManagedIdentityStorage.d.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.
+ */
+declare function fileManagedIdentityStorage(file: string): ManagedIdentityStorage;
+//#endregion
+//#region src/node/principal.d.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`.
+ */
+declare function createSelfManagedPrincipal(identityKey: string): Promise<Principal>;
+/**
+ * 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>`.
+ */
+declare function createSelfManagedPrincipalFromFile(file: string): Promise<Principal>;
+//#endregion
+//#region src/node/headerDelimitedTransport.d.ts
+interface HeaderDelimitedTransportOptions {
+  readonly maxHeaderBytes?: number;
+  readonly maxContentLength?: number;
+  readonly maxPendingMessages?: number;
+}
+/**
+ * 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.
+ */
+declare class HeaderDelimitedTransport implements IMessageTransport {
+  private readonly _input;
+  private readonly _output;
+  private readonly _onClose?;
+  private _listener;
+  private readonly _pending;
+  private _residual;
+  private _expectedLength;
+  private _closed;
+  private _closeReason;
+  private readonly _maxHeaderBytes;
+  private readonly _maxContentLength;
+  private readonly _maxPendingMessages;
+  private readonly _onDataListener;
+  private readonly _onEndListener;
+  private readonly _onInputErrorListener;
+  private readonly _onOutputErrorListener;
+  constructor(_input: NodeJS.ReadableStream, _output: NodeJS.WritableStream, _onClose?: ((reason?: string) => void) | undefined, options?: HeaderDelimitedTransportOptions);
+  get closed(): boolean;
+  get closeReason(): string | undefined;
+  send(message: JsonRpcMessage): Promise<void>;
+  setListener(listener: ((message: JsonRpcMessage) => void) | undefined): void;
+  dispose(): void;
+  close(reason?: string): void;
+  private _onData;
+  private _onEnd;
+  private _deliver;
+}
+//#endregion
+//#region src/node/initialize.d.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.
+ */
+declare const INITIALIZE_METHOD = "hubrpc::initialize";
+/** Transitional alias accepted by servers created during the LinkRPC wire-name migration. */
+declare const LINKRPC_INITIALIZE_METHOD_ALIAS = "linkrpc::initialize";
+/** Current transport protocol version. */
+declare const INITIALIZE_PROTOCOL_VERSION = 1;
+interface InitializeParams {
+  readonly protocolVersion: number;
+  /** Shared-secret auth token, when the transport requires one. */
+  readonly token?: string;
+}
+interface InitializeResult {
+  readonly protocolVersion: number;
+}
+/**
+ * The handshake role for a connection:
+ *  - `client`: send `hubrpc::initialize` and await the reply (the dialing side).
+ *  - `server`: require `hubrpc::initialize` as the first message, validate the
+ *    token, and reply (the accepting side).
+ */
+type InitializeRole = {
+  readonly kind: 'client';
+  readonly token?: string;
+} | {
+  readonly kind: 'server';
+  readonly isTokenAccepted: (token: string | undefined) => Promise<boolean>;
+};
+interface ConnectNdjsonOptions {
+  readonly input: NodeJS.ReadableStream;
+  readonly output: NodeJS.WritableStream;
+  readonly onClose?: () => void;
+  /**
+   * Run a `hubrpc::initialize` handshake before the transport goes live. Omit
+   * for trusted links that need neither auth nor negotiation (e.g. stdio).
+   */
+  readonly initialize?: InitializeRole;
+  /** Observe all messages, including the initialize handshake. */
+  readonly trace?: MessageTransportTrace;
+  /** Override the handshake timeout (ms). */
+  readonly handshakeTimeoutMs?: number;
+}
+interface ConnectedNdjson {
+  /**
+   * The connected transport, already past the handshake. Callers never see
+   * the pre-handshake transport, so the "initialize is the first message"
+   * invariant holds structurally and the wire setup stays free to evolve.
+   */
+  readonly transport: IMessageTransport;
+  /** The token presented by the peer (server role); `undefined` otherwise. */
+  readonly token?: string;
+}
+/**
+ * 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".
+ */
+declare function connectNdjson(opts: ConnectNdjsonOptions): Promise<ConnectedNdjson>;
+interface RunInitializeHandshakeOptions {
+  /** Override the handshake timeout (ms). */
+  readonly handshakeTimeoutMs?: number;
+}
+/**
+ * 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.
+ */
+declare function runInitializeHandshake(transport: IMessageTransport, role: InitializeRole, options?: RunInitializeHandshakeOptions): Promise<{
+  readonly token?: string;
+}>;
+//#endregion
+//#region src/node/webSocketClientTransport.d.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.
+ */
+declare class WebSocketTransport implements IMessageTransport<JsonRpcMessage, JsonRpcMessage> {
+  private readonly _ws;
+  private readonly _onClose?;
+  private _listener;
+  private readonly _buffer;
+  private _closed;
+  constructor(_ws: WebSocket, _onClose?: (() => void) | undefined);
+  send(message: JsonRpcMessage): void;
+  setListener(listener: ((m: JsonRpcMessage) => void) | undefined): void;
+  dispose(): void;
+  private _deliver;
+}
+/** Options for {@link openWebSocket}. */
+interface OpenWebSocketOptions {
+  /** Extra request headers to send on the upgrade. */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * 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.
+ */
+declare function openWebSocket(url: string, opts?: OpenWebSocketOptions): Promise<WebSocket>;
+//#endregion
+export { Ability, type AcceptedRootIssuer, ArraySchema, BareGetOptions, type BareInterfaceTarget, Base64Sha256, BooleanSchema, Call, CallBind, CallMeta, CallTarget, type CancellableRequest, CapBag, CapBagOptions, type CapProvider, type CapProviderResult, Capability, Channel, ChannelConnector, type ChannelTransport, type CmdEnvEndpoint, type CmdStdioEndpoint, Components, type ConnectNdjsonOptions, type ConnectToHubOptions, type ConnectableChannel, type ConnectedNdjson, ConstSchema, DEFAULT_RPC_TIMEOUT_MS, DiscriminatorSchema, EXTENSION_PREFIX, type EndpointCommand, EnumSchema, ErrorCode, ErrorSchema, type ExpBackoffOptions, type FormatEndpointOptions, GenerateInterfaceOptions, GetOptions, HUBRPC_META_KEY, HUBRPC_SIGNATURE_KEY, HUBRPC_UNSIGNED_KEY, HeaderDelimitedTransport, type HeaderDelimitedTransportOptions, type HubChannel, type HubClientHandle, type HubPrefixClaimer, type HubPrefixClaimerOptions, IMessageTransport, INITIALIZE_METHOD, INITIALIZE_PROTOCOL_VERSION, type IRequestHandler, type IRequestSender, Identity, InMemoryManagedIdentity, InMemoryManagedIdentityStorage, type IncomingCall, type IncomingStream, type InitializeParams, type InitializeResult, type InitializeRole, InspectionRegistration, IntegerSchema, InterfaceClient, InterfaceDefinition, InterfaceDefinitionOpts, InterfaceHandlers, InterfaceInfo, InterfaceMemberRef, InterfaceMemberRefMap, InterfaceRegistration, type IssueCapabilityOptions, JsonObject, JsonRpcChannel, JsonRpcError, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccess, JsonValue, KEY_ID_PREFIX, type KeepConnectedHandle, KeyId, Keypair, KeypairIdentity, KeypairSigningIdentity, LINKRPC_ENDPOINT_VAR, LINKRPC_INITIALIZE_METHOD_ALIAS, LINKRPC_META_KEY, LINKRPC_SIGNATURE_KEY, LINKRPC_TOKEN_VAR, LINKRPC_UNSIGNED_KEY, LinkRpcConnection, LinkRpcConnectionOptions, LinkRpcInterfaceSchema, LinkRpcJsonRpcMessage, LinkRpcJsonRpcNotification, LinkRpcJsonRpcRequest, LinkRpcJsonSchema, LinkRpcUnsigned, LinkRpcWireMeta, LinkRpcWireParams, type LoadOrCreateIdentityOptions, ManagedIdentity, ManagedIdentityStorage, ManagedIdentityStorageBackend, type ManagedSigningChannel, MaterializedJsonSchema, MemberAnnotations, MemberDocs, MemberMap, MemberType, MessageTransportDirection, MessageTransportTrace, MessageTransportWithContext, MessageWithContext, type MessageWithCtx, MethodSchema, MultiplexedTransport, MuxEnvelope, NodeInfo, NotificationType, NullSchema, NumberSchema, ObjectSchema, type OnChannelConnect, OneOfSchema, OneShotCapStaging, type OpenHubChannelOptions, type OpenWebSocketOptions, PRINCIPAL_PREFIX, ParamMatcher, type ParamMatcherFor, type ParamMatchers, ParsedMethodName, ParticipantDescriptor, ParticipantDescriptorSource, Pattern, Permission, type PermitResult, type PersistedIdentity, Principal, PrincipalId, PrincipalWithStore, PrivateKey, PublicKey, PublicSigningIdentity, PublicWrappingIdentity, type RawStreamingCall, RefSchema, type RegisterHubPrefixOptions, RegisterOptions, RequestId, RequestType, ResolveSigningKeyArgs, type ResolvedEndpoint, type Result, RootPrincipalReq, RootPrincipalSet, RouteClaim, RpcError, type RunInitializeHandshakeOptions, STREAM_METHOD, Schema, SchemaBase, SchemaToZodContext, SeededPrincipalOptions, type SendOpts, SerializedKeypairSigningIdentity, type ServeOverHubController, type ServeOverHubIdentityOptions, type ServeOverHubOptions, ServiceHandle, ServiceIdPattern, SignDomain, SignParamsOptions, SignRpcCallOptions, Signature, SignatureEnvelope, Signatures, SignedCapability, SignedRpcCall, type SigningCallCtx, SigningIdentity, SigningSender, type SigningSenderConfig, type SocketEndpoint, type StdioChannel, StreamApi, StreamCallOptions, StreamControlReason, StreamControlType, StreamDir, type StreamSendOpts, StreamSendParams, StreamingCall, StringSchema, TargetPattern, TopologyGraph, TopologyIdGenerator, TopologyLink, TopologyLinkEndpoint, TopologyNode, TopologyPort, TopologyTransportEndpoint, TopologyTransportInfo, TrafficEvent, TrafficOverflowEvent, TrafficTransitEndpoint, TrafficTransitEvent, TrafficWatchResult, TransportPair, TupleSchema, UnionSchema, VerifyCallOptions, VerifyResult, VerifyRpcCallOptions, VerifyRpcCallResult, WebSocketTransport, WrappingIdentity, type WsEndpoint, type WsNoInitEndpoint, X25519Keypair, ZodToSvcJsonSchemaOptions, 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_d_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.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","names":[],"sources":["../src/node/stdio.ts","../src/node/hubClient.ts","../src/node/hubReconnect.ts","../src/node/fileManagedIdentityStorage.ts","../src/node/principal.ts","../src/node/headerDelimitedTransport.ts","../src/node/initialize.ts","../src/node/webSocketClientTransport.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAkBsB,kBAAkB,kCAAkC,QAAQ;;;;;;iBAyB5D,gBAAgB,QAAQ;;;;;;;;KAYlC,eAAe;;EAEvB,QAAQ,uBAAuB;;iBAGb,oBAAoB,QAAQ;;;;cCzBrC;;cAEA;UAEI;;WAEJ;;WAEA;;;;;;;WAOA,YAAY;;;;;WAKZ,cAAc;;;;;;;;KASf;EACR,YAAY;EACZ,cAAc;EACd,cAAc;;UAGD;;WAEJ,YAAY,6BAA6B;;;;;;;;WAQzC,KAAK;;WAEL;WACA;;;;;;WAMA,SAAS;;;;;;EAMlB,QAAQ,uBAAuB;;EAE/B;;;;;;;;;;;;iBAakB,aAAa,UAAS,sBAA2B,QAAQ;;UAuB9D;;WAEJ;;;;;;WAMA;;;;;;;;;;;KAYD,aAAa;WACZ;WACA;;;;;EAKT,QAAQ,uBAAuB;;EAE/B;;;;;;;iBAQkB,eAClB,UAAS,wBACV,QAAQ;;;;;;;;;;;UAwGM;WACJ,QAAQ;WACR;;;;;;;;WAQA;aAAsB,WAAW;aAAsB,SAAS;;;;;;;;WAOhE,wBAAwB;;iBAGf,kBAClB,MAAM,2BACP;UA6Bc;;;;;;WAMJ;;WAEA;;;;;;WAMA;;UAGI;WACJ,WAAW;WACX,SAAS;;WAET,aAAa;;WAEb;;;;;;;;;;;;;;;;iBAiBS,qBAClB,MAAM,8BACP,QAAQ;;;UCjWM;;;;;;WAMJ;;;;;WAMA;;;;;;;;;WASA;;;;;WAKA;;UAGI;;WAEJ;;;;;;;;WAQA,QAAQ,YAAY,6BAA6B,2BAA2B;;;;WAI5E;;WAEA,QAAQ;;;;;WAKR;;WAEA;;;;;;WAMA,SAAS;;;;;;;;;;WAUT,WAAW;;UAGP;;EAEb;;;;;WAKS,MAAM;;;;;;;;;;;;;iBAcH,0BACZ,SAAS,sBACV;UA8Dc;;WAEJ;;WAEA,UAAU;;WAEV,OAAO;;UAGH;;;;;;;;EAQb,MAAM,QAAQ,kBAAkB;;;;;;;;;;;;;;;;;;;iBAoBpB,uBAAuB,MAAM,0BAA0B;;;;;;;;;;;iBCrMvD,2BAA2B,eAAe;;;;;;;;;;iBCCpC,2BAA2B,sBAAsB,QAAQ;;;;;;;iBAUzD,mCAAmC,eAAe,QAAQ;;;UCf/D;WACJ;WACA;WACA;;;;;;;;cASA,oCAAoC;mBAmBxB;mBACA;mBACA;UApBb;mBACS;UACT;UACA;UACA;UACA;mBACS;mBACA;mBACA;mBAEA;mBACA;mBACA;mBAEA;EAII,YAAA,QAAQ,OAAO,gBACf,SAAS,OAAO,gBAChB,aAAY,uCAC7B,UAAS;MAkBF;MAIA;EAIJ,KAAK,SAAS,iBAAiB;EAsB/B,YAAY,YAAY,SAAS;EAOjC;EAIA,MAAM;UAYL;UAmDA;UAOA;;;;;;;;;;cC5JC;;cAEA;;cAGA;UAQI;WACJ;;WAEA;;UAGI;WACJ;;;;;;;;KASD;WACK;WAAyB;;WAEzB;WACA,kBAAkB,8BAA8B;;UAGhD;WACJ,OAAO,OAAO;WACd,QAAQ,OAAO;WACf;;;;;WAKA,aAAa;;WAEb,QAAQ;;WAER;;UAGI;;;;;;WAMJ,WAAW;;WAEX;;;;;;;;;;;iBAYS,cAAc,MAAM,uBAAuB,QAAQ;UAuCxD;;WAEJ;;;;;;;;;;;iBAYS,uBAClB,WAAW,mBACX,MAAM,gBACN,UAAS,gCACV;WAAmB;;;;;;;;;;;;;;;;cChIT,8BAA8B,kBAAkB,gBAAgB;mBAMpD;mBACA;UANb;mBACS;UACT;EAGa,YAAA,KAAK,WACL;EAiCd,KAAK,SAAS;EAMd,YAAY,YAAY,GAAG;EAU3B;UASC;;;UAOK;;WAEJ,UAAU;;;;;;;;;;;;;;iBAeP,cACZ,aACA,OAAM,uBACP,QAAQ"}