@procedures/peer 0.0.0-stage → 0.1.0

package/src/peer/index.ts

@@ -0,0 +1,325 @@
+/**
+ * Peer Module
+ *
+ * Transport-agnostic peer implementation for bidirectional RPC.
+ */
+
+import {
+  ProcedureServer,
+  HttpServerTransport,
+  WebSocketServerTransport,
+  type ProcedureRegistry,
+  PROCEDURE_REGISTRY,
+  rpcServerUrlStrategy,
+  defaultServerUrlStrategy,
+  defaultUrlPattern,
+  procedureServerOptions,
+  type BrowserGuardOptions,
+  type HostPolicy,
+  type Method,
+} from "@procedures/client";
+import type { Request } from "express";
+import type { ProcedurePath } from "@procedures/client";
+import type { HttpTransportConfig, TransportConfig, TransportType, WebSocketTransportConfig } from "../types.js";
+import { bearerToken, hostAllowed, originAllowed, tokenMatches } from "./security.js";
+
+/**
+ * URL strategy that matches the client's defaultUrlPattern
+ * Maps: POST /api/server/status → { service: "server", operation: "status" }
+ */
+function patternUrlStrategy(req: Request): Method | null {
+  const basePath = "/api";
+  let path = req.path;
+
+  // Remove base path prefix if present
+  if (path.startsWith(basePath)) {
+    path = path.slice(basePath.length);
+  }
+
+  // Use the client's defaultUrlPattern parser
+  // Cast method to expected type (parser doesn't actually use it for this pattern)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return defaultUrlPattern.parse(path, req.method.toUpperCase() as any);
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface PeerOptions {
+  /** Unique peer ID */
+  id: string;
+  /** Transports to enable */
+  transports: TransportConfig[];
+  /** Auto-register procedures from registry */
+  autoRegister?: boolean;
+  /** Procedure registry to use */
+  registry?: ProcedureRegistry;
+  /** The procedures that the peer serves (see `exposeRule`). Without it, the peer serves every procedure. */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /**
+   * The policy of the host (`hostPolicy()` of the core, roadmap 2.3): the expose rule, the call
+   * rule, the interceptors (a time limit), the token of each network transport that has none of
+   * its own, and the browser checks. `expose` above, when given, wins over the policy's.
+   */
+  policy?: HostPolicy | undefined;
+}
+
+export interface PeerEndpoint {
+  type: TransportType;
+  address: string;
+}
+
+export interface Peer {
+  /** Peer ID */
+  id: string;
+  /** Start all transports */
+  start(): Promise<void>;
+  /** Stop all transports */
+  stop(): Promise<void>;
+  /** Get active endpoints */
+  getEndpoints(): PeerEndpoint[];
+  /** Get underlying server */
+  getServer(): ProcedureServer;
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+class PeerImpl implements Peer {
+  readonly id: string;
+  private server: ProcedureServer;
+  private transports: TransportConfig[];
+  private endpoints: PeerEndpoint[] = [];
+  private started = false;
+  private registry: ProcedureRegistry;
+  private startTime: number = Date.now();
+
+  /** The browser checks of the policy (an origin rule here replaces the peer's own rule). */
+  private browser: BrowserGuardOptions;
+
+  constructor(options: PeerOptions) {
+    this.id = options.id;
+    const policy = options.policy;
+    // The policy's token goes to each network transport that has none of its own
+    this.transports = options.transports.map((transport) =>
+      transport.type === "local" || policy?.token === undefined || transport.token !== undefined
+        ? transport
+        : { ...transport, token: policy.token }
+    );
+    this.registry = options.registry ?? PROCEDURE_REGISTRY;
+    this.browser = policy?.browser ?? {};
+
+    // Create procedure server
+    this.server = new ProcedureServer({
+      ...(policy ? procedureServerOptions(policy, this.registry) : {}),
+      autoRegister: options.autoRegister ?? true,
+      registry: this.registry,
+      ...(options.expose ? { expose: options.expose } : {}),
+    });
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+
+    try {
+      for (const transport of this.transports) {
+        await this.startTransport(transport);
+      }
+    } catch (error) {
+      // Stop the transports that started, so a failed start leaves no port open
+      await this.server.stop().catch(() => {});
+      this.endpoints = [];
+      throw error;
+    }
+
+    this.started = true;
+  }
+
+  private async startTransport(config: TransportConfig): Promise<void> {
+    switch (config.type) {
+      case "http":
+        await this.startHttpTransport(config);
+        break;
+      case "websocket":
+        await this.startWebSocketTransport(config);
+        break;
+      case "local":
+        // Local transport doesn't need network setup
+        this.endpoints.push({
+          type: "local",
+          address: "local://in-process",
+        });
+        break;
+    }
+  }
+
+  private async startHttpTransport(config: HttpTransportConfig): Promise<void> {
+    // Dynamic import to avoid bundling express if not used
+    const express = (await import("express")).default;
+
+    const app = express();
+    app.use(express.json());
+
+    const port = config.port ?? 3000;
+    // Loopback by default so the full procedure registry (incl. shell.run / fs.write) is not
+    // served unauthenticated on all interfaces. Pass host: "0.0.0.0" to expose on the LAN
+    // deliberately. See documentation/BUGS-2026-07.md (H19).
+    const host = config.host ?? "127.0.0.1";
+    const basePath = config.basePath ?? "/api";
+
+    // Host, origin and token checks (deep dive TRN-1, CLI-1, CLI-2). The health endpoints need no
+    // token: a client uses them to check that a lockfile's server is alive.
+    app.use((req, res, next) => {
+      if (!hostAllowed(host, req.headers.host) || !originAllowed(req.headers.origin, config.corsOrigins)) {
+        res.status(403).json({ error: "Forbidden: the host or the origin is not allowed", code: "FORBIDDEN" });
+        return;
+      }
+      const isHealth = req.path === "/health" || req.path === `${basePath}/health`;
+      if (!isHealth && req.method !== "OPTIONS" && !tokenMatches(config.token, bearerToken(req.headers.authorization))) {
+        res.status(401).json({ error: "Unauthorized: this server requires its token", code: "UNAUTHORIZED" });
+        return;
+      }
+      next();
+    });
+
+    // Health endpoint for container orchestration
+    app.get(`${basePath}/health`, (_req, res) => {
+      const procedureCount = this.registry.getAll().filter((p) => p.handler).length;
+      res.json({
+        status: "ok",
+        uptime: Date.now() - this.startTime,
+        procedures: procedureCount,
+        peerId: this.id,
+      });
+    });
+
+    // Also add at root /health for convenience
+    app.get("/health", (_req, res) => {
+      const procedureCount = this.registry.getAll().filter((p) => p.handler).length;
+      res.json({
+        status: "ok",
+        uptime: Date.now() - this.startTime,
+        procedures: procedureCount,
+        peerId: this.id,
+      });
+    });
+
+    // Select URL strategy based on config
+    // Default to patternUrlStrategy which matches the client's defaultUrlPattern
+    const urlStrategy = config.urlStrategy === "rpc"
+      ? rpcServerUrlStrategy
+      : config.urlStrategy === "rest"
+        ? defaultServerUrlStrategy
+        : patternUrlStrategy;
+
+    const httpTransport = new HttpServerTransport(this.server, {
+      app,
+      port,
+      host,
+      basePath,
+      // Off by default: before, every peer sent Access-Control-Allow-Origin: * (deep dive CLI-2)
+      cors: config.cors ?? false,
+      urlStrategy,
+      // The transport's browser checks follow the peer's rule: loopback origins and the listed
+      // ones (the token is required in any case). The RESTful strategy calls by GET.
+      allowedOrigins: this.browser.allowedOrigins ?? ((origin) => originAllowed(origin, config.corsOrigins)),
+      ...(this.browser.allowedHosts ? { allowedHosts: this.browser.allowedHosts } : {}),
+      allowGet: this.browser.allowGet ?? config.urlStrategy === "rest",
+    });
+
+    this.server.addTransport(httpTransport);
+    await httpTransport.start();
+
+    this.endpoints.push({
+      type: "http",
+      address: `http://${host === "0.0.0.0" ? "localhost" : host}:${port}${basePath}`,
+    });
+  }
+
+  private async startWebSocketTransport(config: WebSocketTransportConfig): Promise<void> {
+    // WebSocket transport requires an HTTP server to attach to
+    // For standalone WebSocket, we create an HTTP server first
+    const { createServer } = await import("http");
+
+    const port = config.port ?? 3001;
+    // Loopback by default so the full procedure registry (incl. shell.run / fs.write) is not
+    // served unauthenticated on all interfaces. Pass host: "0.0.0.0" to expose on the LAN
+    // deliberately. See documentation/BUGS-2026-07.md (H19).
+    const host = config.host ?? "127.0.0.1";
+    const path = config.path ?? "/ws";
+
+    const httpServer = createServer();
+
+    // Listen first, then attach the WebSocket server. A listen error (EADDRINUSE, EACCES) rejects:
+    // before, the error had no listener, so the process ended with an unhandled 'error' event
+    // (deep dive CLI-16).
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error): void => {
+        reject(new Error(`The WebSocket server cannot listen on ${host}:${port}: ${error.message}`));
+      };
+      httpServer.once("error", onError);
+      httpServer.listen(port, host, () => {
+        httpServer.off("error", onError);
+        resolve();
+      });
+    });
+
+    const wsTransport = new WebSocketServerTransport(this.server, {
+      server: httpServer,
+      path,
+      allowedOrigins: this.browser.allowedOrigins ?? ((origin) => originAllowed(origin, config.origins)),
+      ...(this.browser.allowedHosts ? { allowedHosts: this.browser.allowedHosts } : {}),
+      // Host, origin and token checks: before, any web page could open a connection and call
+      // procedures (cross-site WebSocket hijacking, deep dive TRN-1)
+      authenticate: (req) => {
+        const token = new URL(req.url ?? "/", "http://localhost").searchParams.get("token") ?? bearerToken(req.headers.authorization);
+        return (
+          hostAllowed(host, req.headers.host) &&
+          originAllowed(req.headers.origin, config.origins) &&
+          tokenMatches(config.token, token)
+        );
+      },
+    });
+
+    this.server.addTransport(wsTransport);
+    try {
+      await wsTransport.start();
+    } catch (error) {
+      httpServer.close();
+      throw error;
+    }
+
+    this.endpoints.push({
+      type: "websocket",
+      address: `ws://${host === "0.0.0.0" ? "localhost" : host}:${port}${path}`,
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this.started) return;
+    await this.server.stop();
+    this.started = false;
+    this.endpoints = [];
+  }
+
+  getEndpoints(): PeerEndpoint[] {
+    return [...this.endpoints];
+  }
+
+  getServer(): ProcedureServer {
+    return this.server;
+  }
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a new peer instance
+ */
+export async function createPeer(options: PeerOptions): Promise<Peer> {
+  return new PeerImpl(options);
+}

package/src/peer/security.ts

@@ -0,0 +1,58 @@
+/**
+ * Request checks of a peer (deep dive TRN-1, CLI-1, CLI-2).
+ *
+ * A peer serves the whole registry, `shell.*` included. So:
+ * - a peer bound to loopback answers only requests addressed to a loopback name (a DNS
+ *   rebinding attack sends another name);
+ * - a browser request is accepted only from a loopback origin or an origin in the allowlist
+ *   (before, CORS was on by default with `Access-Control-Allow-Origin: *`, so any web page could
+ *   call the server);
+ * - when the peer has a token, every request must carry it: `Authorization: Bearer <token>` over
+ *   HTTP, `?token=<token>` for a WebSocket connection (a browser WebSocket cannot set headers).
+ */
+
+import { timingSafeEqual } from "node:crypto";
+
+const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+/** True for a bind address that only this computer can reach. */
+export function isLoopback(host: string): boolean {
+  return LOOPBACK_NAMES.has(host);
+}
+
+/** The name of a Host header without its port: "localhost:3000" gives "localhost", "[::1]:80" gives "[::1]". */
+export function hostName(header: string | undefined): string {
+  if (!header) return "";
+  if (header.startsWith("[")) return header.slice(0, header.indexOf("]") + 1).toLowerCase();
+  return (header.split(":")[0] ?? "").toLowerCase();
+}
+
+/** A peer bound to loopback accepts only a loopback Host header. */
+export function hostAllowed(bindHost: string, header: string | undefined): boolean {
+  return !isLoopback(bindHost) || LOOPBACK_NAMES.has(hostName(header));
+}
+
+/** A request without Origin (not a browser) passes; a browser origin must be loopback or in the allowlist. */
+export function originAllowed(origin: string | undefined, allowlist: readonly string[] = []): boolean {
+  if (origin === undefined) return true;
+  if (allowlist.includes(origin)) return true;
+  try {
+    return LOOPBACK_NAMES.has(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** True when no token is required, or when the presented token is the expected one (a constant-time comparison). */
+export function tokenMatches(expected: string | undefined, presented: string | undefined | null): boolean {
+  if (expected === undefined) return true;
+  if (!presented) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(presented);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/** The token of an `Authorization: Bearer <token>` header. */
+export function bearerToken(header: string | undefined): string | undefined {
+  return header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+}

package/src/procedures/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Server Procedures
+ *
+ * All procedures exported from this module.
+ */
+
+export { serverCreateProcedure, getPeer, getActivePeerIds } from "./server.create.js";
+export type { ServerCreateInput, ServerCreateOutput } from "./server.create.js";
+
+export { serverConnectProcedure } from "./server.connect.js";
+export type { ServerConnectInput, ServerConnectOutput } from "./server.connect.js";
+
+export { serverDisconnectProcedure } from "./server.disconnect.js";
+export type { ServerDisconnectInput, ServerDisconnectOutput } from "./server.disconnect.js";
+
+export { manifestGenerateProcedure } from "./manifest.generate.js";
+export type { ManifestGenerateInput, ManifestGenerateOutput } from "./manifest.generate.js";
+
+export { serverStartProcedure } from "./server.start.js";
+export type { ServerStartInput, ServerStartOutput } from "./server.start.js";
+
+export { serverStopProcedure } from "./server.stop.js";
+export type { ServerStopInput, ServerStopOutput } from "./server.stop.js";
+
+export { serverStatusProcedure } from "./server.status.js";
+export type { ServerStatusInput, ServerStatusOutput } from "./server.status.js";
+
+export { serverCallProcedure } from "./server.call.js";
+export type { ServerCallInput, ServerCallOutput } from "./server.call.js";
+
+export { serverConnectionsProcedure } from "./server.connections.js";
+export type { ServerConnectionsInput, ServerConnectionsOutput } from "./server.connections.js";

package/src/procedures/manifest.generate.ts

@@ -0,0 +1,113 @@
+/**
+ * Procedure: manifest.generate
+ * Generates procedure manifests in various formats
+ */
+
+import { createProcedure, jsonSchemaOf, type Procedure, PROCEDURE_REGISTRY } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ManifestGenerateOutputSchema } from "../output-schemas.js";
+import { manifestGenerateInputSchema } from "../input-schemas.js";
+import type { ManifestGenerateInput, ManifestGenerateOutput, ProcedureInfo } from "../types.js";
+import { generateTypeScript } from "../manifest/typescript.js";
+import { generateJson } from "../manifest/json.js";
+import { writeFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+
+// Use pass-through schemas
+const manifestGenerateOutputSchema = wrapSchema<ManifestGenerateOutput>(ManifestGenerateOutputSchema);
+
+export const manifestGenerateProcedure: Procedure<
+  ManifestGenerateInput,
+  ManifestGenerateOutput,
+  { description: string }
+> = createProcedure()
+  .path(["manifest", "generate"])
+  .input(manifestGenerateInputSchema)
+  .output(manifestGenerateOutputSchema)
+  .meta({ description: "Generate procedure manifests in various formats" })
+  .handler(async (input: ManifestGenerateInput) => {
+    // Get all registered procedures
+    const allProcedures = PROCEDURE_REGISTRY.getAll();
+
+    // Filter by namespace if specified
+    let procedures = allProcedures;
+    if (input.namespace && input.namespace.length > 0) {
+      procedures = allProcedures.filter((proc) => {
+        // Check if procedure path starts with namespace
+        for (let i = 0; i < input.namespace!.length; i++) {
+          if (proc.path[i] !== input.namespace![i]) {
+            return false;
+          }
+        }
+        return true;
+      });
+    }
+
+    // Convert to ProcedureInfo format
+    const procedureInfos: ProcedureInfo[] = procedures.map((proc) => {
+      const meta = proc.metadata as { description?: string; internal?: boolean } | undefined;
+      const info: ProcedureInfo = {
+        path: proc.path,
+      };
+      if (meta?.description !== undefined) {
+        info.description = meta.description;
+      }
+      // The JSON Schemas of the input and the output, when the schemas can describe themselves
+      const inputSchema = jsonSchemaOf(proc.input, { io: "input" });
+      const outputSchema = jsonSchemaOf(proc.output, { io: "output" });
+      if (inputSchema) info.inputSchema = inputSchema;
+      if (outputSchema) info.outputSchema = outputSchema;
+      return info;
+    });
+
+    // Determine formats to generate
+    const formats = input.formats ?? ["json"];
+    const result: ManifestGenerateOutput = {};
+    const filesWritten: string[] = [];
+
+    // Generate JSON manifest
+    if (formats.includes("json")) {
+      const jsonManifest = generateJson(procedureInfos);
+      result.json = jsonManifest;
+
+      if (input.outputDir) {
+        const filePath = join(input.outputDir, "procedures.json");
+        await ensureDir(dirname(filePath));
+        await writeFile(filePath, JSON.stringify(jsonManifest, null, 2));
+        filesWritten.push(filePath);
+      }
+    }
+
+    // Generate TypeScript declarations
+    if (formats.includes("typescript")) {
+      const typescript = generateTypeScript(procedureInfos);
+      result.typescript = typescript;
+
+      if (input.outputDir) {
+        const filePath = join(input.outputDir, "procedures.d.ts");
+        await ensureDir(dirname(filePath));
+        await writeFile(filePath, typescript);
+        filesWritten.push(filePath);
+      }
+    }
+
+    if (filesWritten.length > 0) {
+      result.filesWritten = filesWritten;
+    }
+
+    return result;
+  })
+  .build();
+
+/**
+ * Ensure directory exists
+ */
+async function ensureDir(dir: string): Promise<void> {
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch {
+    // Directory may already exist
+  }
+}
+
+export type { ManifestGenerateInput, ManifestGenerateOutput };

package/src/procedures/server.call.ts

@@ -0,0 +1,96 @@
+/**
+ * Procedure: server.call
+ * Call a procedure on a remote peer through an outbound connection
+ */
+
+import { createProcedure, pathToMethod, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerCallOutputSchema } from "../output-schemas.js";
+import { serverCallInputSchema } from "../input-schemas.js";
+import { getConnection, connect } from "../connection/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ServerCallInput {
+  /** Connection ID (from server.connect) */
+  connectionId?: string | undefined;
+  /** Remote address (alternative to connectionId - creates one-shot connection) */
+  address?: string | undefined;
+  /** Procedure path on the remote peer - dot-separated string or array */
+  path: string | string[];
+  /** Input payload for the remote procedure */
+  input?: unknown;
+}
+
+export interface ServerCallOutput {
+  /** Result from the remote procedure */
+  result: unknown;
+  /** Connection ID used */
+  connectionId: string;
+  /** Procedure path called */
+  path: string[];
+}
+
+// =============================================================================
+// Procedure
+// =============================================================================
+
+const serverCallOutputSchema = wrapSchema<ServerCallOutput>(ServerCallOutputSchema);
+
+export const serverCallProcedure: Procedure<
+  ServerCallInput,
+  ServerCallOutput,
+  { description: string; args: string[]; shorts: Record<string, string>; output: string }
+> = createProcedure()
+  .path(["server", "call"])
+  .input(serverCallInputSchema)
+  .output(serverCallOutputSchema)
+  .meta({
+    description: "Call a procedure on a remote peer through an outbound connection",
+    args: ["path"],
+    shorts: { connectionId: "c", address: "a" },
+    output: "json",
+  })
+  .handler(async (input: ServerCallInput): Promise<ServerCallOutput> => {
+    // Normalize path: accept dot-separated string or array
+    const pathArray = typeof input.path === "string"
+      ? input.path.split(".")
+      : input.path;
+
+    // Resolve connection: by ID, or create one-shot from address
+    let connectionId: string;
+    let client: import("@procedures/client").Client;
+
+    if (input.connectionId) {
+      const connection = getConnection(input.connectionId);
+      if (!connection) {
+        throw new Error(
+          `Connection not found: ${input.connectionId}. Use 'server connect' first, or pass --address.`
+        );
+      }
+      connectionId = connection.id;
+      client = connection.client;
+    } else if (input.address) {
+      // Create a connection on-the-fly
+      const connection = await connect({ address: input.address });
+      connectionId = connection.id;
+      client = connection.client;
+    } else {
+      throw new Error("Either connectionId or address is required");
+    }
+
+    // Convert procedure path to Method format for client.call: the core mapping of every host
+    // (deep dive architecture review 3.3)
+    const method = pathToMethod(pathArray);
+
+    const result = await client.call(method, input.input ?? {});
+
+    return {
+      result,
+      connectionId,
+      path: pathArray,
+    };
+  })
+  .build();

package/src/procedures/server.connect.ts

@@ -0,0 +1,45 @@
+/**
+ * Procedure: server.connect
+ * Connects to a remote peer for bidirectional RPC
+ */
+
+import { createProcedure, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerConnectOutputSchema } from "../output-schemas.js";
+import { serverConnectInputSchema } from "../input-schemas.js";
+import type { ServerConnectInput, ServerConnectOutput } from "../types.js";
+import { connect } from "../connection/index.js";
+
+// Use pass-through schemas
+const serverConnectOutputSchema = wrapSchema<ServerConnectOutput>(ServerConnectOutputSchema);
+
+export const serverConnectProcedure: Procedure<
+  ServerConnectInput,
+  ServerConnectOutput,
+  { description: string }
+> = createProcedure()
+  .path(["server", "connect"])
+  .input(serverConnectInputSchema)
+  .output(serverConnectOutputSchema)
+  .meta({ description: "Connect to a remote peer for bidirectional RPC", args: ["address"] })
+  .handler(async (input: ServerConnectInput) => {
+    const connectOptions: Parameters<typeof connect>[0] = {
+      address: input.address,
+    };
+    if (input.transport !== undefined) {
+      connectOptions.transport = input.transport;
+    }
+    if (input.timeout !== undefined) {
+      connectOptions.timeout = input.timeout;
+    }
+    const connection = await connect(connectOptions);
+
+    return {
+      connectionId: connection.id,
+      remotePeerId: connection.remote.remotePeerId,
+      remoteProcedures: connection.remote.remoteProcedures,
+    };
+  })
+  .build();
+
+export type { ServerConnectInput, ServerConnectOutput };