@procedures/client 0.0.0-stage → 0.2.0

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 };
+}

package/src/server/host-policy.ts

@@ -0,0 +1,163 @@
+/**
+ * The policy of a host: one place that builds what a server lets its callers do (roadmap 2.3).
+ *
+ * The three hosts (the MCP dev-tools server, the `server` CLI, the warm server of `mark`) each
+ * built their own expose rule, call rule, time limit and token. `hostPolicy()` builds them from
+ * one set of options, and `procedureServerOptions()` gives them to a `ProcedureServer`.
+ *
+ * - `expose`: the procedures that callers reach. Patterns: an exact key (`git.status`), a prefix
+ *   (`git.*`) or `*`. A tool surface: namespaces and the keys to leave out. Without it: every
+ *   procedure.
+ * - `strictCalls`: a procedure of code that declares no `metadata.calls` calls only exposed
+ *   procedures (a host for an outside caller sets it).
+ * - `timeoutMs`: the time limit of each call from a caller (not of its nested calls).
+ * - `token`, `browser`: the checks of the network transports (`client-server` applies them).
+ * - `capability`, `readOnly`, `clearanceOrder`, `resources`, `admitItem`: the capability of each
+ *   call and what the host gives for it (CAPABILITIES-2026-10).
+ */
+
+import type { Capability, ClearanceOrder, ProcedurePath, ResourcesOf } from "../procedures/types.js";
+import type { Interceptor, Invocation } from "../procedures/invoke.js";
+import { narrowCapability } from "../procedures/capability.js";
+import type { ServerRequest } from "./types.js";
+import { timeoutInterceptor } from "../procedures/interceptors.js";
+import type { BrowserGuardOptions } from "./browser-guard.js";
+import type { ProcedureRegistry } from "../procedures/registry.js";
+import type { ProcedureServerOptions } from "./procedure-server.js";
+
+/** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
+export interface ToolSurface {
+  namespaces: readonly string[];
+  exclude?: readonly string[] | undefined;
+}
+
+/** The rule of a list of patterns: an exact key (`git.status`), a prefix (`git.*`) or `*`. */
+export function exposePatterns(patterns: readonly string[]): (path: ProcedurePath) => boolean {
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  let all = false;
+  for (const pattern of patterns) {
+    if (pattern === "*") all = true;
+    else if (pattern.endsWith(".*")) prefixes.push(pattern.slice(0, -1));
+    else exact.add(pattern);
+  }
+  return (path) => {
+    if (all) return true;
+    const key = path.join(".");
+    return exact.has(key) || prefixes.some((prefix) => key.startsWith(prefix));
+  };
+}
+
+/** The rule of a tool surface: the namespaces, less the excluded keys. */
+export function surfaceRule(surface: ToolSurface): (path: ProcedurePath) => boolean {
+  const namespaces = new Set(surface.namespaces);
+  const excluded = new Set(surface.exclude ?? []);
+  return (path) => namespaces.has(path[0] ?? "") && !excluded.has(path.join("."));
+}
+
+/** The options of `hostPolicy()`. */
+export interface HostPolicyOptions {
+  /** The procedures that callers reach. Without it: every procedure of the registry. */
+  expose?: readonly string[] | ToolSurface | ((path: ProcedurePath) => boolean) | undefined;
+  /** Keys that callers do not reach, also when `expose` matches them. */
+  exclude?: readonly string[] | undefined;
+  /** A procedure of code with no `metadata.calls` calls only exposed procedures. */
+  strictCalls?: boolean | undefined;
+  /** The time limit of each call from a caller, in milliseconds. 0 or no value: no limit. */
+  timeoutMs?: number | undefined;
+  /** More interceptors, after the policy's own (tracing, metrics). */
+  interceptors?: readonly Interceptor[] | undefined;
+  /** The token that each network request must send (HTTP and WebSocket transports). */
+  token?: string | undefined;
+  /** The browser checks of the network transports (`allowedOrigins`, `allowedHosts`, `allowGet`). */
+  browser?: BrowserGuardOptions | undefined;
+  /**
+   * The capability of each call from a caller: one value, or a function of the request. The
+   * function reads only what the transport authenticated (the token, a session), not a claim of
+   * the caller. Without it: no limits.
+   */
+  capability?: Capability | ((request: ServerRequest<unknown>) => Capability | undefined) | undefined;
+  /** True: the callers start only the procedures that change nothing (`effects.writes` is empty). */
+  readOnly?: boolean | undefined;
+  /** The order of the clearance values. */
+  clearanceOrder?: ClearanceOrder | undefined;
+  /** The resources of each invocation for its capability (`ctx.resources`). */
+  resources?: ((invocation: Invocation) => ResourcesOf) | undefined;
+  /** The filter of the output that leaves the host. */
+  admitItem?: ((item: unknown, invocation: Invocation) => boolean) | undefined;
+}
+
+/** What a host lets its callers do. */
+export interface HostPolicy {
+  readonly expose: ((path: ProcedurePath) => boolean) | undefined;
+  readonly strictCalls: boolean;
+  readonly interceptors: readonly Interceptor[];
+  readonly token: string | undefined;
+  readonly browser: BrowserGuardOptions;
+  /** The capability of a call from a caller, or undefined for no limits. */
+  readonly capabilityOf: ((request?: ServerRequest<unknown>) => Capability | undefined) | undefined;
+  readonly clearanceOrder: ClearanceOrder | undefined;
+  readonly resources: ((invocation: Invocation) => ResourcesOf) | undefined;
+  readonly admitItem: ((item: unknown, invocation: Invocation) => boolean) | undefined;
+}
+
+/** The capability function of a policy: the capability of the options, narrowed by `readOnly`. */
+function capabilityOfOptions(options: HostPolicyOptions): HostPolicy["capabilityOf"] {
+  const { capability, readOnly } = options;
+  if (capability === undefined && !readOnly) return undefined;
+  const readOnlyRequest = readOnly ? { effects: { writes: [] as readonly string[] } } : undefined;
+  return (request) => {
+    const base = typeof capability === "function" ? (request ? capability(request) : undefined) : capability;
+    return readOnlyRequest ? narrowCapability(base, readOnlyRequest, options.clearanceOrder) : base;
+  };
+}
+
+function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean) | undefined {
+  const { expose } = options;
+  const rule =
+    expose === undefined
+      ? undefined
+      : typeof expose === "function"
+        ? expose
+        : Array.isArray(expose)
+          ? exposePatterns(expose as readonly string[])
+          : surfaceRule(expose as ToolSurface);
+  const excluded = new Set(options.exclude ?? []);
+  if (excluded.size === 0) return rule;
+  return (path) => !excluded.has(path.join(".")) && (rule ? rule(path) : true);
+}
+
+/** This function builds the policy of a host from its options. */
+export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
+  const interceptors: Interceptor[] = [];
+  if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+    interceptors.push(timeoutInterceptor({ ms: options.timeoutMs }));
+  }
+  interceptors.push(...(options.interceptors ?? []));
+  return {
+    expose: exposeOf(options),
+    strictCalls: options.strictCalls ?? false,
+    interceptors,
+    token: options.token,
+    browser: options.browser ?? {},
+    capabilityOf: capabilityOfOptions(options),
+    clearanceOrder: options.clearanceOrder,
+    resources: options.resources,
+    admitItem: options.admitItem,
+  };
+}
+
+/** The options of a `ProcedureServer` that serves a registry under a policy. */
+export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureRegistry): ProcedureServerOptions {
+  return {
+    autoRegister: true,
+    ...(registry ? { registry } : {}),
+    ...(policy.expose ? { expose: policy.expose } : {}),
+    strictCalls: policy.strictCalls,
+    ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
+    ...(policy.capabilityOf ? { capability: policy.capabilityOf } : {}),
+    ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),
+    ...(policy.resources ? { resources: policy.resources } : {}),
+    ...(policy.admitItem ? { admitItem: policy.admitItem } : {}),
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Universal Server
+ *
+ * Protocol-agnostic RPC server architecture.
+ * Mirrors the universal client for symmetrical design.
+ *
+ * Features:
+ * - Protocol-agnostic (HTTP, WebSocket, gRPC via adapters)
+ * - Unified RPC format internally
+ * - Middleware support
+ * - Handler registry with pattern matching
+ * - Graceful shutdown
+ *
+ * @example
+ * ```typescript
+ * import { Server, HttpServerTransport } from "@common/server";
+ *
+ * const server = new Server();
+ *
+ * // Register handlers
+ * server.register(
+ *   { service: "users", operation: "get" },
+ *   async (req) => ({
+ *     id: req.id,
+ *     status: { type: "success", code: 200 },
+ *     payload: { id: req.payload.id, name: "John" },
+ *     metadata: {}
+ *   })
+ * );
+ *
+ * // Add HTTP transport
+ * const httpTransport = new HttpServerTransport(server, { port: 3000 });
+ * await httpTransport.start();
+ * ```
+ */
+
+export { Server } from "./server.js";
+export type { ServerOptions } from "./server.js";
+
+export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig } from "./procedure-server.js";
+export { pathToMethod, methodToPath } from "./method.js";
+export {
+  HandlerNotFoundError,
+  ServerError,
+  type ServerRequest,
+  type ServerResponse,
+  type ServerHandler,
+  type ServerMiddleware,
+  type ServerContext,
+  type ServerRunner,
+  type ServerTransport,
+} from "./types.js";
+
+export {
+  HttpServerTransport,
+  defaultServerUrlStrategy,
+  rpcServerUrlStrategy,
+} from "../adapters/http/server/index.js";
+export type {
+  HttpServerTransportOptions,
+  HttpUrlStrategy,
+} from "../adapters/http/server/index.js";
+export { WebSocketServerTransport } from "../adapters/websocket/server/index.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage,
+} from "../adapters/websocket/server/index.js";

package/src/server/method.ts

@@ -0,0 +1,33 @@
+/**
+ * The one mapping between a procedure path and a transport method.
+ *
+ * A path `["docker", "compose", "up"]` is the method `{ service: "docker.compose", operation: "up" }`:
+ * the last segment is the operation, and the other segments are the service. Before, some hosts
+ * sent `{ service: "docker", operation: "compose.up" }` and others the form above, and the
+ * server matched methods exactly, so a 3-segment procedure was not found through a warm server
+ * (deep dive architecture review 3.3).
+ *
+ * `methodToPath` splits both the service and the operation on ".", so it reads both forms.
+ */
+
+import type { Method } from "../client/types.js";
+import type { ProcedurePath } from "../procedures/types.js";
+
+/**
+ * This function gives the transport method of a procedure path. A path needs at least two
+ * segments, because a method has a service and an operation.
+ */
+export function pathToMethod(path: readonly string[]): Method {
+  if (path.length < 2) {
+    throw new Error(`Invalid procedure path (it needs two segments or more): ${path.join(".")}`);
+  }
+  return { service: path.slice(0, -1).join("."), operation: path[path.length - 1]! };
+}
+
+/**
+ * This function gives the procedure path of a transport method. It accepts both encodings:
+ * `{ service: "a.b", operation: "c" }` and `{ service: "a", operation: "b.c" }` give `["a", "b", "c"]`.
+ */
+export function methodToPath(method: Pick<Method, "service" | "operation">): ProcedurePath {
+  return [...method.service.split("."), ...method.operation.split(".")].filter((segment) => segment !== "");
+}