@procedures/client 0.0.0-stage → 0.1.0

package/src/procedures/types.ts

@@ -0,0 +1,485 @@
+/**
+ * Procedure Type System
+ *
+ * Core types for procedure definitions, handlers, and registration.
+ * Procedures are the foundation for typed RPC calls with schema validation.
+ */
+
+import type { ZodErrorLike } from "../client/validation/types.js";
+import type { ProcedureSchema } from "./schema.js";
+import type { CollectionStorage } from "./collection/storage.js";
+import type { EventBus } from "../events/types.js";
+import type { HydrationEvent } from "./ref.js";
+
+// =============================================================================
+// Procedure Path
+// =============================================================================
+
+/**
+ * Procedure path as array of segments.
+ * Forms a tree structure for nested routing.
+ *
+ * @example
+ * ```typescript
+ * ['collections', 'users', 'get']  // collections.users.get
+ * ['weather', 'forecast']           // weather.forecast
+ * ```
+ */
+export type ProcedurePath = string[];
+
+/**
+ * Convert path array to dot-separated key.
+ */
+export function pathToKey(path: ProcedurePath): string {
+  return path.join(".");
+}
+
+/**
+ * Parse dot-separated key to path array.
+ */
+export function keyToPath(key: string): ProcedurePath {
+  return key.split(".");
+}
+
+// =============================================================================
+// Procedure Metadata
+// =============================================================================
+
+/**
+ * Metadata for procedure documentation and categorization.
+ */
+export interface ProcedureMetadata {
+  /** Human-readable description */
+  description?: string;
+
+  /** Tags for categorization and filtering */
+  tags?: string[];
+
+  /** Whether this procedure is deprecated */
+  deprecated?: boolean;
+
+  /** Deprecation message with migration guidance */
+  deprecationMessage?: string;
+
+  /**
+   * The procedures that this procedure calls through `ctx.client`: keys (`"shell.run"`) or
+   * namespaces (`"fs.*"`). A host with a call policy lets the procedure call only these and the
+   * exposed procedures (see `policy.ts`, deep dive MCP-3). `"*"` alone is not allowed: a
+   * procedure whose callees come from its input has the `runs-refs` tag.
+   */
+  calls?: readonly string[];
+
+  /** Custom metadata fields */
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Procedure Context
+// =============================================================================
+
+/**
+ * Repository provider for storage access.
+ * Injected into procedure handlers for data access.
+ */
+export interface RepositoryProvider {
+  /**
+   * Get storage for a collection.
+   *
+   * @param collection - Collection name
+   * @returns Storage instance for the collection
+   */
+  getStorage<T>(collection: string): CollectionStorage<T>;
+
+  /**
+   * Check if a collection exists.
+   *
+   * @param collection - Collection name
+   */
+  hasCollection(collection: string): boolean;
+}
+
+/**
+ * Context passed to procedure handlers.
+ * Contains request metadata and service access.
+ */
+export interface ProcedureContext {
+  /** Request metadata (auth, tracing, etc.) */
+  metadata: Record<string, unknown>;
+
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+
+  /** Repository provider for storage access */
+  repository?: RepositoryProvider;
+
+  /** The full path that was called */
+  path: ProcedurePath;
+
+  /**
+   * Event bus for pub/sub messaging.
+   * Use for streaming coordination and inter-procedure communication.
+   *
+   * @example
+   * ```typescript
+   * // Subscribe to updates in a streaming handler
+   * handler: async function* (input, ctx) {
+   *   yield await getInitial(input.id);
+   *
+   *   for await (const update of ctx.bus.stream(`entity:${input.id}`)) {
+   *     yield update;
+   *   }
+   * }
+   *
+   * // Emit events from another procedure
+   * handler: async (input, ctx) => {
+   *   const result = await saveEntity(input);
+   *   ctx.bus.emit(`entity:${input.id}`, result);
+   *   return result;
+   * }
+   * ```
+   */
+  bus?: EventBus;
+
+  /**
+   * Client for calling other procedures.
+   * Enables inter-procedure communication via the RPC mechanism.
+   *
+   * @example
+   * ```typescript
+   * handler: async (input, ctx) => {
+   *   // Call fs.mkdir procedure
+   *   await ctx.client.call(["fs", "mkdir"], { path: input.dir });
+   *
+   *   // Call git.init procedure  
+   *   await ctx.client.call(["git", "init"], { cwd: input.dir });
+   *
+   *   return { created: true };
+   * }
+   * ```
+   */
+  client: ProcedureClient;
+
+  /**
+   * The registry of the caller: `ctx.client` finds the nested procedures here. A procedure that
+   * reads or changes the registry (`procedure.define`, `client.lookup`) uses this one. When it is
+   * not set, such a procedure uses `PROCEDURE_REGISTRY`.
+   */
+  registry?: ProcedureRegistryLike;
+
+  /**
+   * The hydration observer of the program that runs this procedure (`client.exec(ref, input,
+   * { onRef })`). A procedure that hydrates refs itself (control flow, a runner) gives it to
+   * `hydrateInput`, so a trace sees the events of its own program only.
+   */
+  onRef?: ((event: HydrationEvent) => void) | undefined;
+}
+
+/**
+ * The part of `ProcedureRegistry` that a procedure can use through `ctx.registry`.
+ */
+export interface ProcedureRegistryLike {
+  get(path: ProcedurePath): AnyProcedure | undefined;
+  has(path: ProcedurePath): boolean;
+  getAll(): AnyProcedure[];
+  register(procedure: AnyProcedure, options?: RegistrationOptions): void;
+  unregister(path: ProcedurePath): boolean;
+}
+
+/**
+ * Interface for procedure-to-procedure calls.
+ * Implemented by both Client and ProcedureServer's internal caller.
+ */
+export interface ProcedureClient {
+  /**
+   * Call a procedure by path. For a streaming procedure, the result is the last item.
+   */
+  call<TInput = unknown, TOutput = unknown>(
+    path: ProcedurePath,
+    input: TInput
+  ): Promise<TOutput>;
+
+  /**
+   * Call a procedure by path and read each output: each item of a streaming procedure, or the
+   * one value of another procedure. The procedure starts when the caller reads the first item.
+   * An older client has no `stream`.
+   */
+  stream?<TInput = unknown, TOutput = unknown>(
+    path: ProcedurePath,
+    input: TInput
+  ): AsyncIterable<TOutput>;
+}
+
+// =============================================================================
+// Procedure Handler
+// =============================================================================
+
+/**
+ * Standard procedure handler function (single return).
+ * Receives validated input and context, returns output.
+ *
+ * @example
+ * ```typescript
+ * const handler: StandardHandler<{ id: string }, User> = async (input, ctx) => {
+ *   const storage = ctx.repository?.getStorage<User>('users');
+ *   const user = await storage?.get(input.id);
+ *   if (!user) throw new Error('User not found');
+ *   return user;
+ * };
+ * ```
+ */
+export type StandardHandler<TInput = unknown, TOutput = unknown> = (
+  input: TInput,
+  context: ProcedureContext
+) => Promise<TOutput> | TOutput;
+
+/**
+ * Generator procedure handler (streaming/multi-yield).
+ * Yields output values one or more times.
+ *
+ * @example
+ * ```typescript
+ * // Single yield (same as standard, but generator syntax)
+ * const handler: GeneratorHandler<{ id: string }, User> = async function* (input, ctx) {
+ *   const user = await fetchUser(input.id);
+ *   yield user;  // yields once
+ * };
+ *
+ * // Multi-yield streaming
+ * const handler: GeneratorHandler<{ roomId: string }, Message> = async function* (input, ctx) {
+ *   // Initial data
+ *   yield await getInitialMessages(input.roomId);
+ *
+ *   // Stream updates
+ *   for await (const msg of ctx.bus.stream(`room:${input.roomId}`)) {
+ *     yield msg;  // yields many times
+ *   }
+ * };
+ * ```
+ */
+export type GeneratorHandler<TInput = unknown, TOutput = unknown> = (
+  input: TInput,
+  context: ProcedureContext
+) => AsyncGenerator<TOutput, void, unknown>;
+
+/**
+ * Procedure handler function - supports both standard and generator forms.
+ *
+ * - **Standard handlers**: Return a single value (sync or async)
+ * - **Generator handlers**: Yield one or more values
+ *
+ * The caller's consumption mode (sponge/stream/handlers) determines
+ * how the output is delivered, regardless of handler type.
+ *
+ * @example
+ * ```typescript
+ * // Standard handler (single return)
+ * const handler: ProcedureHandler<{ id: string }, User> = async (input, ctx) => {
+ *   return await fetchUser(input.id);
+ * };
+ *
+ * // Generator handler (streaming)
+ * const handler: ProcedureHandler<{ query: string }, SearchResult> = async function* (input, ctx) {
+ *   for await (const result of search(input.query)) {
+ *     yield result;
+ *   }
+ * };
+ * ```
+ */
+export type ProcedureHandler<TInput = unknown, TOutput = unknown> =
+  | StandardHandler<TInput, TOutput>
+  | GeneratorHandler<TInput, TOutput>;
+
+// =============================================================================
+// Procedure Definition
+// =============================================================================
+
+/**
+ * Full procedure definition with schemas and optional handler.
+ *
+ * @example
+ * ```typescript
+ * const getUserProcedure: Procedure<GetUserInput, User> = {
+ *   path: ['users', 'get'],
+ *   input: z.object({ id: z.string() }),
+ *   output: z.object({ id: z.string(), name: z.string() }),
+ *   metadata: { description: 'Get user by ID', tags: ['users', 'read'] },
+ *   handler: async ({ id }, ctx) => { ... },
+ * };
+ * ```
+ */
+export interface Procedure<
+  TInput = unknown,
+  TOutput = unknown,
+  TMeta extends ProcedureMetadata = ProcedureMetadata
+> {
+  /** Path in the route tree */
+  path: ProcedurePath;
+
+  /** Input validation schema: a Standard Schema (zod 4, valibot, arktype) or a `ZodLike` */
+  input: ProcedureSchema<TInput>;
+
+  /** Output validation schema: a Standard Schema or a `ZodLike` */
+  output: ProcedureSchema<TOutput>;
+
+  /** Procedure metadata for documentation */
+  metadata: TMeta;
+
+  /**
+   * Whether this procedure supports streaming (multi-yield).
+   * When true, the handler is expected to be a generator that may yield multiple times.
+   * When false or undefined, the procedure yields exactly once.
+   *
+   * This is a capability declaration - callers can still consume
+   * streaming procedures in sponge mode (getting only the final value).
+   */
+  streaming?: boolean | undefined;
+
+  /**
+   * Output mode declaration - how the procedure produces its output.
+   *
+   * - `single`: Returns a single value (default) - most procedures
+   * - `stream`: Returns multiple values over time (generator that yields many times)
+   * - `batch`: Returns an array of values all at once
+   *
+   * The consumer can choose their consumption mode (sponge/stream/handlers)
+   * independently. The system translates automatically:
+   *
+   * | Producer Mode | Consumer Mode | Result Type              |
+   * |---------------|---------------|--------------------------|
+   * | single        | sponge        | Promise<T>               |
+   * | single        | stream        | AsyncIterable<T> (1 item)|
+   * | stream        | sponge        | Promise<T> (last value)  |
+   * | stream        | stream        | AsyncIterable<T>         |
+   * | batch         | sponge        | Promise<T[]>             |
+   * | batch         | stream        | AsyncIterable<T>         |
+   */
+  outputMode?: 'single' | 'stream' | 'batch' | undefined;
+
+  /** Server-side handler implementation (optional for stubs and aggregations) */
+  handler?: ProcedureHandler<TInput, TOutput> | undefined;
+}
+
+/**
+ * Procedure without type parameters for generic storage.
+ * Uses `any` for handler to allow covariant/contravariant type compatibility.
+ */
+export type AnyProcedure = Procedure<any, any, ProcedureMetadata>;
+
+// =============================================================================
+// Output Mode Types
+// =============================================================================
+
+/**
+ * How a procedure produces its output.
+ */
+export type OutputMode = 'single' | 'stream' | 'batch';
+
+/**
+ * Default output mode when not specified.
+ */
+export const DEFAULT_OUTPUT_MODE: OutputMode = 'single';
+
+// =============================================================================
+// Procedure Result Types
+// =============================================================================
+
+/**
+ * Result of a procedure call.
+ */
+export type ProcedureResult<TOutput> =
+  | { success: true; data: TOutput }
+  | { success: false; error: ProcedureError };
+
+/**
+ * Error from procedure execution.
+ */
+export interface ProcedureError {
+  /** Error code */
+  code: string;
+
+  /** Error message */
+  message: string;
+
+  /** Whether the error is retryable */
+  retryable: boolean;
+
+  /** Validation errors if applicable */
+  validationErrors?: ZodErrorLike;
+
+  /** The procedure path that failed */
+  path: ProcedurePath;
+}
+
+// =============================================================================
+// Infer Types from Procedure
+// =============================================================================
+
+/**
+ * Infer input type from a procedure.
+ */
+export type InferProcedureInput<T> = T extends Procedure<infer TInput, any, any>
+  ? TInput
+  : unknown;
+
+/**
+ * Infer output type from a procedure.
+ */
+export type InferProcedureOutput<T> = T extends Procedure<any, infer TOutput, any>
+  ? TOutput
+  : unknown;
+
+/**
+ * Infer metadata type from a procedure.
+ */
+export type InferProcedureMetadata<T> = T extends Procedure<any, any, infer TMeta>
+  ? TMeta
+  : ProcedureMetadata;
+
+// =============================================================================
+// Registry Events
+// =============================================================================
+
+/**
+ * Event types emitted by ProcedureRegistry.
+ */
+export type RegistryEventType = "register" | "unregister";
+
+/**
+ * Listener for registry events.
+ */
+export interface RegistryListener {
+  event: RegistryEventType;
+  listener: (procedure: AnyProcedure) => void;
+}
+
+// =============================================================================
+// Module Registration
+// =============================================================================
+
+/**
+ * Module that exports procedures for registration.
+ */
+export interface ProcedureModule {
+  /** Array of procedures exported by this module */
+  procedures: AnyProcedure[];
+
+  /** Optional module name for debugging */
+  name?: string;
+
+  /**
+   * The modules whose procedures this module calls (for example `client-lib` calls `fs.*` and
+   * `git.*`). `createRegistry()` registers them too.
+   */
+  requires?: readonly ProcedureModule[] | undefined;
+}
+
+/**
+ * Registration options for bulk procedure registration.
+ */
+export interface RegistrationOptions {
+  /** Override existing procedures with same path */
+  override?: boolean;
+
+  /** Prefix to prepend to all paths */
+  pathPrefix?: ProcedurePath;
+}

package/src/server/browser-guard.ts

@@ -0,0 +1,147 @@
+/**
+ * Checks of requests that a web browser can send to a procedure server.
+ *
+ * A server serves its whole registry, often with `shell.*` in it, and a web page that the user
+ * opens can send requests to `127.0.0.1`. Before, the HTTP server transport read any request
+ * body as JSON, so a "simple" cross-site POST (`Content-Type: text/plain`, no CORS preflight)
+ * ran any procedure, and the WebSocket server accepted a connection from any page
+ * (cross-site WebSocket hijacking). The checks here are on by default in both transports:
+ *
+ * - A connection that arrives on a loopback address must name a loopback host in its `Host`
+ *   header. A DNS rebinding attack sends the name of the attacker's site.
+ * - A browser request (an `Origin` header) must come from the server's own origin, or from an
+ *   origin in `allowedOrigins`.
+ * - A request that the browser marks `Sec-Fetch-Site: cross-site` or `same-site` and that has
+ *   no allowed origin is refused (an image tag or a form sends no `Origin` for a GET).
+ * - HTTP only: a procedure call by GET or HEAD is refused unless `allowGet` is true, and a
+ *   request body must be JSON.
+ */
+
+import type { IncomingHttpHeaders } from "node:http";
+
+const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+/** The options of the browser checks of a server transport. */
+export interface BrowserGuardOptions {
+  /**
+   * The web origins that can call the server, besides its own origin. `"*"` allows every
+   * origin. A function decides for each origin.
+   * @default [] (only the server's own origin)
+   */
+  allowedOrigins?: readonly string[] | "*" | ((origin: string) => boolean) | undefined;
+  /**
+   * The host names that a request on a loopback address can name in its `Host` header,
+   * besides the loopback names. `"*"` turns the check off.
+   * @default [] (only `localhost`, `127.0.0.1` and `[::1]`)
+   */
+  allowedHosts?: readonly string[] | "*" | undefined;
+  /**
+   * HTTP only: accept procedure calls by GET or HEAD. A RESTful URL strategy needs this. A GET
+   * is a request that any page can send (an image tag), so it is off by default.
+   * @default false
+   */
+  allowGet?: boolean | undefined;
+}
+
+/** The parts of an incoming request that the checks read. */
+export interface GuardedRequest {
+  method?: string | undefined;
+  headers: IncomingHttpHeaders;
+  socket?: { localAddress?: string | undefined } | undefined;
+}
+
+/** The result of the checks: the request passes, or the HTTP status and the error to send. */
+export type GuardResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly status: 403 | 405 | 415; readonly code: string; readonly message: string };
+
+/** True for a host name or a bind address that only this computer can reach. */
+export function isLoopbackHost(host: string): boolean {
+  return LOOPBACK_NAMES.has(host.toLowerCase());
+}
+
+/** True for a local socket address on the loopback interface (IPv4, IPv6, or IPv4 in IPv6). */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (!address) return false;
+  const plain = address.startsWith("::ffff:") ? address.slice("::ffff:".length) : address;
+  return plain === "::1" || plain.startsWith("127.");
+}
+
+/** The name of a Host header without its port: "localhost:3000" gives "localhost", "[::1]:80" gives "[::1]". */
+export function hostNameOf(header: string | undefined): string {
+  if (!header) return "";
+  if (header.startsWith("[")) return header.slice(0, header.indexOf("]") + 1).toLowerCase();
+  return (header.split(":")[0] ?? "").toLowerCase();
+}
+
+function originAllowedBy(origin: string, allowed: BrowserGuardOptions["allowedOrigins"]): boolean {
+  if (allowed === "*") return true;
+  if (typeof allowed === "function") return allowed(origin);
+  return (allowed ?? []).includes(origin);
+}
+
+/** True when the origin is the origin of the server that the request names in its Host header. */
+function sameOrigin(origin: string, hostHeader: string | undefined): boolean {
+  if (!hostHeader) return false;
+  try {
+    return new URL(origin).host.toLowerCase() === hostHeader.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/** True for a media type of JSON: `application/json` or a `+json` type. */
+function isJsonType(contentType: string | undefined): boolean {
+  const type = (contentType ?? "").split(";")[0]!.trim().toLowerCase();
+  return type === "application/json" || type.endsWith("+json");
+}
+
+/** True when the request has a body: a `Content-Length` above 0, or a chunked body. */
+function hasBody(headers: IncomingHttpHeaders): boolean {
+  const length = Number(headers["content-length"] ?? 0);
+  return length > 0 || headers["transfer-encoding"] !== undefined;
+}
+
+/**
+ * The checks of the host, the origin and the fetch site, for HTTP and WebSocket requests.
+ * `http` adds the checks of the method and the body.
+ */
+export function checkBrowserRequest(
+  req: GuardedRequest,
+  options: BrowserGuardOptions = {},
+  http = false
+): GuardResult {
+  const { headers } = req;
+
+  // DNS rebinding: a request on a loopback address must name a loopback host
+  if (options.allowedHosts !== "*" && isLoopbackAddress(req.socket?.localAddress)) {
+    const name = hostNameOf(headers.host);
+    if (!LOOPBACK_NAMES.has(name) && !(options.allowedHosts ?? []).includes(name)) {
+      return { ok: false, status: 403, code: "FORBIDDEN_HOST", message: `Forbidden: the host "${name}" is not allowed` };
+    }
+  }
+
+  const origin = typeof headers.origin === "string" ? headers.origin : undefined;
+  if (origin !== undefined) {
+    if (!sameOrigin(origin, headers.host) && !originAllowedBy(origin, options.allowedOrigins)) {
+      return { ok: false, status: 403, code: "FORBIDDEN_ORIGIN", message: `Forbidden: the origin "${origin}" is not allowed` };
+    }
+  } else {
+    const site = headers["sec-fetch-site"];
+    if ((site === "cross-site" || site === "same-site") && options.allowedOrigins !== "*") {
+      return { ok: false, status: 403, code: "FORBIDDEN_ORIGIN", message: "Forbidden: a request from another site" };
+    }
+  }
+
+  if (http) {
+    const method = (req.method ?? "GET").toUpperCase();
+    if ((method === "GET" || method === "HEAD") && !options.allowGet) {
+      return { ok: false, status: 405, code: "METHOD_NOT_ALLOWED", message: "Call a procedure with POST" };
+    }
+    if (hasBody(headers) && !isJsonType(headers["content-type"])) {
+      return { ok: false, status: 415, code: "UNSUPPORTED_MEDIA_TYPE", message: "The request body must be JSON (Content-Type: application/json)" };
+    }
+  }
+
+  return { ok: true };
+}