@aria-cli/tools 1.0.0

package/src/runtime-socket-local-control-client.ts

@@ -0,0 +1,632 @@
+import * as net from "node:net";
+import { randomUUID } from "node:crypto";
+import type {
+  AttachedClientAuth,
+  AttachedLocalControlApi,
+  LocalControlApi,
+  RunHandle,
+  ResumeRunRequest,
+  RuntimeRunEvent,
+  RuntimeEventCursor,
+} from "./types.js";
+import type {
+  AcceptInviteRequest,
+  AcceptInviteResponse,
+  AcceptInviteTokenRequest,
+  AcceptInviteTokenResponse,
+  DirectPairRequest,
+  DirectPairResponse,
+  CancelInviteRequest,
+  CancelInviteResponse,
+  CreateInviteRequest,
+  CreateInviteResponse,
+  InboxCursor,
+  InboxListRequest,
+  InvitePeerRequest,
+  InvitePeerResult,
+  NodeId,
+  NearbyPeerView,
+  OutboundMessage,
+  PairRequestDecision,
+  PairRequestResponse,
+  PendingInviteView,
+  PendingPairRequestView,
+  PeerViewEvent,
+  PersistedInboxEvent,
+  RepairPeerRequest,
+  RepairPeerResponse,
+  RevokePeerRequest,
+  RevokePeerResponse,
+  RuntimeAutonomousLoopCommand,
+  RuntimeDeliveryReceipt,
+  RuntimeQueuedReceipt,
+  RuntimeStatus,
+  RuntimeBootstrapRecord,
+  RuntimeEvent,
+  RunRequest,
+  RunResult,
+  LocalControlSocketMethod,
+} from "./network-runtime/index.js";
+import {
+  AcceptInviteRequestSchema,
+  AcceptInviteResponseSchema,
+  AcceptInviteTokenRequestSchema,
+  AcceptInviteTokenResponseSchema,
+  AttachedClientAuthSchema,
+  AttachedClientViewSchema,
+  CancelInviteRequestSchema,
+  CancelInviteResponseSchema,
+  CreateInviteRequestSchema,
+  CreateInviteResponseSchema,
+  InboxAddressSchema,
+  InboxCursorSchema,
+  InboxListRequestSchema,
+  DirectPairRequestSchema,
+  DirectPairResponseSchema,
+  InvitePeerRequestSchema,
+  InvitePeerResultSchema,
+  NearbyPeerViewSchema,
+  OutboundMessageSchema,
+  PairRequestDecisionSchema,
+  PairRequestResponseSchema,
+  PendingInviteViewSchema,
+  PendingPairRequestViewSchema,
+  PeerViewEventSchema,
+  PersistedInboxEventSchema,
+  RepairPeerRequestSchema,
+  RepairPeerResponseSchema,
+  RevokePeerRequestSchema,
+  RevokePeerResponseSchema,
+  ResumeRunRequestSchema,
+  RunRequestSchema,
+  RunResultSchema,
+  RuntimeDeliveryReceiptSchema,
+  RuntimeEventCursorSchema,
+  RuntimeEventSchema,
+  RuntimeQueuedReceiptSchema,
+  RuntimeRunEventSchema,
+  RuntimeStatusSchema,
+  RuntimeAutonomousLoopCommandSchema,
+  RuntimeBootstrapRecordSchema,
+  createTrustedRuntimeError,
+  LocalControlSocketRequestSchema,
+  LocalControlSocketResponseSchema,
+} from "./network-runtime/index.js";
+
+function createOneShotHandle(resultPromise: Promise<RunResult>): RunHandle {
+  return {
+    runId: `run-local-${Date.now()}`,
+    wait: () => resultPromise,
+  };
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, Math.max(ms, 0)));
+}
+
+async function* createPollingSubscription<
+  T extends { id?: string; nodeId?: NodeId; createdAt?: number },
+>(
+  loadOnce: () => Promise<T[]>,
+  options: {
+    pollIntervalMs: number;
+    initialAfterCreatedAt?: number;
+    getVersionKey?: (item: T) => string | number;
+  } = { pollIntervalMs: 1_000 },
+): AsyncIterable<T> {
+  const seenVersions = new Map<string, string | number>();
+  let afterCreatedAt = options.initialAfterCreatedAt ?? 0;
+
+  while (true) {
+    const snapshot = await loadOnce();
+    let emitted = false;
+
+    for (const item of snapshot) {
+      if (typeof item.createdAt === "number" && item.createdAt < afterCreatedAt) {
+        continue;
+      }
+      const identity = typeof item.id === "string" ? item.id : item.nodeId;
+      if (typeof identity === "string") {
+        const versionKey = options.getVersionKey?.(item) ?? JSON.stringify(item);
+        if (seenVersions.get(identity) === versionKey) {
+          continue;
+        }
+        seenVersions.set(identity, versionKey);
+      }
+      if (typeof item.createdAt === "number") {
+        afterCreatedAt = Math.max(afterCreatedAt, item.createdAt);
+      }
+      emitted = true;
+      yield item;
+    }
+
+    if (!emitted) {
+      await sleep(options.pollIntervalMs);
+    }
+  }
+}
+
+function requestRuntimeSocket<T>(
+  runtimeSocket: string,
+  method: LocalControlSocketMethod,
+  payload: unknown,
+  parse: (raw: unknown) => T,
+  auth?: AttachedClientAuth,
+): Promise<T> {
+  const request = LocalControlSocketRequestSchema.parse({
+    id: randomUUID(),
+    method,
+    ...(payload === undefined ? {} : { payload }),
+    ...(auth === undefined ? {} : { auth: AttachedClientAuthSchema.parse(auth) }),
+  });
+
+  return new Promise<T>((resolve, reject) => {
+    const socket = net.createConnection(runtimeSocket);
+    let buffer = "";
+    let settled = false;
+
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(error);
+    };
+
+    socket.setEncoding("utf8");
+    socket.once("error", fail);
+    socket.once("connect", () => {
+      socket.write(`${JSON.stringify(request)}\n`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1 || settled) return;
+
+      settled = true;
+      socket.destroy();
+      try {
+        const response = LocalControlSocketResponseSchema.parse(
+          JSON.parse(buffer.slice(0, newlineIndex)),
+        );
+        if (response.id !== request.id) {
+          reject(new Error("Local control socket response ID mismatch"));
+          return;
+        }
+        if (!response.ok) {
+          const trustedError = createTrustedRuntimeError(response.error, response.diagnostic);
+          // Propagate reason sub-code for stale-lease detection
+          if ("reason" in response && typeof response.reason === "string") {
+            (trustedError as Error & { reason?: string }).reason = response.reason;
+          }
+          reject(trustedError);
+          return;
+        }
+        resolve(parse(response.payload));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    socket.once("end", () => {
+      if (!settled) {
+        fail(new Error("Local control socket closed before sending a response"));
+      }
+    });
+  });
+}
+
+function requestRuntimeSocketStream<T>(
+  runtimeSocket: string,
+  method: LocalControlSocketMethod,
+  payload: unknown,
+  parse: (raw: unknown) => T,
+  signal?: AbortSignal,
+  auth?: AttachedClientAuth,
+): AsyncIterable<T> {
+  const request = LocalControlSocketRequestSchema.parse({
+    id: randomUUID(),
+    method,
+    ...(payload === undefined ? {} : { payload }),
+    ...(auth === undefined ? {} : { auth: AttachedClientAuthSchema.parse(auth) }),
+  });
+
+  return {
+    async *[Symbol.asyncIterator](): AsyncIterator<T> {
+      const socket = net.createConnection(runtimeSocket);
+      let buffer = "";
+      let ended = false;
+      let pendingError: unknown;
+      const queued: T[] = [];
+      let wake: (() => void) | undefined;
+
+      const notify = () => {
+        const resolve = wake;
+        wake = undefined;
+        resolve?.();
+      };
+
+      socket.setEncoding("utf8");
+      socket.once("connect", () => {
+        socket.write(`${JSON.stringify(request)}\n`);
+      });
+      const onAbort = () => {
+        ended = true;
+        socket.destroy();
+        notify();
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      socket.on("data", (chunk) => {
+        buffer += chunk;
+        while (true) {
+          const newlineIndex = buffer.indexOf("\n");
+          if (newlineIndex === -1) break;
+          const line = buffer.slice(0, newlineIndex).trim();
+          buffer = buffer.slice(newlineIndex + 1);
+          if (line.length === 0) {
+            continue;
+          }
+          try {
+            const response = LocalControlSocketResponseSchema.parse(JSON.parse(line));
+            if (response.id !== request.id) {
+              pendingError = new Error("Local control socket response ID mismatch");
+              break;
+            }
+            if (!response.ok) {
+              const streamError = createTrustedRuntimeError(response.error, response.diagnostic);
+              if ("reason" in response && typeof response.reason === "string") {
+                (streamError as Error & { reason?: string }).reason = response.reason;
+              }
+              pendingError = streamError;
+              break;
+            }
+            queued.push(parse(response.payload));
+          } catch (error) {
+            pendingError = error;
+            break;
+          }
+        }
+        notify();
+      });
+      socket.once("error", (error) => {
+        pendingError = error;
+        notify();
+      });
+      socket.once("end", () => {
+        ended = true;
+        notify();
+      });
+      socket.once("close", () => {
+        ended = true;
+        notify();
+      });
+
+      try {
+        while (true) {
+          if (queued.length > 0) {
+            yield queued.shift()!;
+            continue;
+          }
+          if (pendingError) {
+            throw pendingError;
+          }
+          if (ended) {
+            return;
+          }
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+        }
+      } finally {
+        signal?.removeEventListener("abort", onAbort);
+        socket.destroy();
+      }
+    },
+  };
+}
+
+export function createRuntimeSocketLocalControlClient(options: {
+  runtimeSocket: string;
+  pollIntervalMs?: number;
+}): LocalControlApi {
+  const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+  const listInbox = async (request?: InboxListRequest): Promise<PersistedInboxEvent[]> =>
+    requestRuntimeSocket(
+      options.runtimeSocket,
+      "listInbox",
+      InboxListRequestSchema.optional().parse(request),
+      (raw) => PersistedInboxEventSchema.array().parse(raw),
+    );
+
+  return {
+    async submitRun(request: RunRequest): Promise<RunHandle> {
+      const payload = RunRequestSchema.parse(request);
+      return createOneShotHandle(
+        requestRuntimeSocket(options.runtimeSocket, "submitRun", payload, (raw) =>
+          RunResultSchema.parse(raw),
+        ),
+      );
+    },
+    async resumeRun(request: ResumeRunRequest) {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "resumeRun",
+        ResumeRunRequestSchema.parse(request),
+        (raw) => RunResultSchema.parse(raw),
+      );
+    },
+    streamRun(request: RunRequest, signal?: AbortSignal): AsyncIterable<RuntimeRunEvent> {
+      return requestRuntimeSocketStream(
+        options.runtimeSocket,
+        "streamRun",
+        RunRequestSchema.parse(request),
+        (raw) => RuntimeRunEventSchema.parse(raw),
+        signal,
+      );
+    },
+    subscribeRuntimeEvents(cursor?: RuntimeEventCursor): AsyncIterable<RuntimeEvent> {
+      return requestRuntimeSocketStream(
+        options.runtimeSocket,
+        "subscribeRuntimeEvents",
+        RuntimeEventCursorSchema.optional().parse(cursor),
+        (raw) => RuntimeEventSchema.parse(raw),
+      );
+    },
+    async sendBestEffort(message: OutboundMessage): Promise<RuntimeQueuedReceipt> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "sendBestEffort",
+        OutboundMessageSchema.parse(message),
+        (raw) => RuntimeQueuedReceiptSchema.parse(raw),
+      );
+    },
+    async sendDurable(message: OutboundMessage): Promise<RuntimeDeliveryReceipt> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "sendDurable",
+        OutboundMessageSchema.parse(message),
+        (raw) => RuntimeDeliveryReceiptSchema.parse(raw),
+      );
+    },
+    listInbox,
+    subscribeInbox(cursor?: InboxCursor): AsyncIterable<PersistedInboxEvent> {
+      return createPollingSubscription(() => listInbox({ limit: 100, unreadOnly: false }), {
+        pollIntervalMs,
+        initialAfterCreatedAt: cursor?.afterCreatedAt ?? 0,
+      });
+    },
+    async listPeers(): Promise<PeerViewEvent[]> {
+      return requestRuntimeSocket(options.runtimeSocket, "listPeers", undefined, (raw) =>
+        PeerViewEventSchema.array().parse(raw),
+      );
+    },
+    async listNearbyPeers(): Promise<NearbyPeerView[]> {
+      return requestRuntimeSocket(options.runtimeSocket, "listNearbyPeers", undefined, (raw) =>
+        NearbyPeerViewSchema.array().parse(raw),
+      );
+    },
+    subscribePeers(): AsyncIterable<PeerViewEvent> {
+      return createPollingSubscription(
+        () =>
+          requestRuntimeSocket(options.runtimeSocket, "listPeers", undefined, (raw) =>
+            PeerViewEventSchema.array().parse(raw),
+          ),
+        {
+          pollIntervalMs,
+          getVersionKey: (peer) =>
+            [
+              peer.updatedAt,
+              peer.endpointRevision,
+              peer.identityState,
+              peer.transportState,
+              peer.lastSeenAt ?? "",
+              peer.transportPublicKey,
+              peer.displayNameSnapshot ?? "",
+            ].join("|"),
+        },
+      );
+    },
+    async getRuntimeStatus(): Promise<RuntimeStatus> {
+      return requestRuntimeSocket(options.runtimeSocket, "getRuntimeStatus", undefined, (raw) =>
+        RuntimeStatusSchema.parse(raw),
+      );
+    },
+    async startAutonomousLoop(input?: RuntimeAutonomousLoopCommand): Promise<RuntimeStatus> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "startAutonomousLoop",
+        RuntimeAutonomousLoopCommandSchema.optional().parse(input),
+        (raw) => RuntimeStatusSchema.parse(raw),
+      );
+    },
+    async stopAutonomousLoop(): Promise<RuntimeStatus> {
+      return requestRuntimeSocket(options.runtimeSocket, "stopAutonomousLoop", undefined, (raw) =>
+        RuntimeStatusSchema.parse(raw),
+      );
+    },
+    async getRuntimeBootstrap(): Promise<RuntimeBootstrapRecord> {
+      return requestRuntimeSocket(options.runtimeSocket, "getRuntimeBootstrap", undefined, (raw) =>
+        RuntimeBootstrapRecordSchema.parse(raw),
+      );
+    },
+    async listPendingPairRequests(): Promise<PendingPairRequestView[]> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "listPendingPairRequests",
+        undefined,
+        (raw) => PendingPairRequestViewSchema.array().parse(raw),
+      );
+    },
+    async respondToPairRequest(input: PairRequestDecision): Promise<PairRequestResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "respondToPairRequest",
+        PairRequestDecisionSchema.parse(input),
+        (raw) => PairRequestResponseSchema.parse(raw),
+      );
+    },
+    async createInvite(input: CreateInviteRequest): Promise<CreateInviteResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "createInvite",
+        CreateInviteRequestSchema.parse(input),
+        (raw) => CreateInviteResponseSchema.parse(raw),
+      );
+    },
+    async listPendingInvites(): Promise<PendingInviteView[]> {
+      return requestRuntimeSocket(options.runtimeSocket, "listPendingInvites", undefined, (raw) =>
+        PendingInviteViewSchema.array().parse(raw),
+      );
+    },
+    async acceptInviteToken(input: AcceptInviteTokenRequest): Promise<AcceptInviteTokenResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "acceptInviteToken",
+        AcceptInviteTokenRequestSchema.parse(input),
+        (raw) => AcceptInviteTokenResponseSchema.parse(raw),
+      );
+    },
+    async cancelInvite(input: CancelInviteRequest): Promise<CancelInviteResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "cancelInvite",
+        CancelInviteRequestSchema.parse(input),
+        (raw) => CancelInviteResponseSchema.parse(raw),
+      );
+    },
+    async invitePeer(input: InvitePeerRequest): Promise<InvitePeerResult> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "invitePeer",
+        InvitePeerRequestSchema.parse(input),
+        (raw) => InvitePeerResultSchema.parse(raw),
+      );
+    },
+    async acceptInvite(input: AcceptInviteRequest): Promise<AcceptInviteResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "acceptInvite",
+        AcceptInviteRequestSchema.parse(input),
+        (raw) => AcceptInviteResponseSchema.parse(raw),
+      );
+    },
+    async directPair(input: DirectPairRequest): Promise<DirectPairResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "directPair",
+        DirectPairRequestSchema.parse(input),
+        (raw) => DirectPairResponseSchema.parse(raw),
+      );
+    },
+    async revokePeer(input: RevokePeerRequest): Promise<RevokePeerResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "revokePeer",
+        RevokePeerRequestSchema.parse(input),
+        (raw) => RevokePeerResponseSchema.parse(raw),
+      );
+    },
+    async repairPeer(input: RepairPeerRequest): Promise<RepairPeerResponse> {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "repairPeer",
+        RepairPeerRequestSchema.parse(input),
+        (raw) => RepairPeerResponseSchema.parse(raw),
+      );
+    },
+  };
+}
+
+export function createRuntimeSocketAttachedLocalControlClient(options: {
+  runtimeSocket: string;
+  auth: AttachedClientAuth;
+  pollIntervalMs?: number;
+}): AttachedLocalControlApi {
+  const auth = AttachedClientAuthSchema.parse(options.auth);
+  const base = createRuntimeSocketLocalControlClient({
+    runtimeSocket: options.runtimeSocket,
+    pollIntervalMs: options.pollIntervalMs,
+  });
+
+  const listDirectClientInbox = async (
+    request?: InboxListRequest,
+  ): Promise<PersistedInboxEvent[]> =>
+    requestRuntimeSocket(
+      options.runtimeSocket,
+      "listDirectClientInbox",
+      InboxListRequestSchema.optional().parse(request),
+      (raw) => PersistedInboxEventSchema.array().parse(raw),
+      auth,
+    );
+
+  return {
+    ...base,
+    async sendBestEffort(message) {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "sendBestEffort",
+        OutboundMessageSchema.parse(message),
+        (raw) => RuntimeQueuedReceiptSchema.parse(raw),
+        auth,
+      );
+    },
+    async sendDurable(message) {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "sendDurable",
+        OutboundMessageSchema.parse(message),
+        (raw) => RuntimeDeliveryReceiptSchema.parse(raw),
+        auth,
+      );
+    },
+    async submitRun(request) {
+      const payload = RunRequestSchema.parse(request);
+      return createOneShotHandle(
+        requestRuntimeSocket(
+          options.runtimeSocket,
+          "submitRun",
+          payload,
+          (raw) => RunResultSchema.parse(raw),
+          auth,
+        ),
+      );
+    },
+    async resumeRun(request) {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "resumeRun",
+        ResumeRunRequestSchema.parse(request),
+        (raw) => RunResultSchema.parse(raw),
+        auth,
+      );
+    },
+    streamRun(request, signal) {
+      return requestRuntimeSocketStream(
+        options.runtimeSocket,
+        "streamRun",
+        RunRequestSchema.parse(request),
+        (raw) => RuntimeRunEventSchema.parse(raw),
+        signal,
+        auth,
+      );
+    },
+    async listAttachedClients() {
+      return requestRuntimeSocket(
+        options.runtimeSocket,
+        "listAttachedClients",
+        undefined,
+        (raw) => AttachedClientViewSchema.array().parse(raw),
+        auth,
+      );
+    },
+    listDirectClientInbox,
+    subscribeDirectClientInbox(cursor?: InboxCursor): AsyncIterable<PersistedInboxEvent> {
+      return requestRuntimeSocketStream(
+        options.runtimeSocket,
+        "subscribeDirectClientInbox",
+        InboxCursorSchema.optional().parse(cursor),
+        (raw) => PersistedInboxEventSchema.parse(raw),
+        undefined,
+        auth,
+      );
+    },
+  };
+}

package/src/security/dns-normalization.ts

@@ -0,0 +1,34 @@
+import type { LookupAddress } from "node:dns";
+
+export interface NormalizedLookupAddress {
+  address: string;
+  family: 4 | 6;
+}
+
+function isLookupAddress(value: unknown): value is NormalizedLookupAddress {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const candidate = value as { address?: unknown; family?: unknown };
+  return (
+    typeof candidate.address === "string" && (candidate.family === 4 || candidate.family === 6)
+  );
+}
+
+export function normalizeLookupResult(
+  lookupResult: LookupAddress | LookupAddress[] | unknown,
+): NormalizedLookupAddress[] {
+  if (Array.isArray(lookupResult)) {
+    return lookupResult.filter(isLookupAddress).map((entry) => ({
+      address: entry.address,
+      family: entry.family,
+    }));
+  }
+
+  if (isLookupAddress(lookupResult)) {
+    return [{ address: lookupResult.address, family: lookupResult.family }];
+  }
+
+  return [];
+}