@procedures/client 0.7.0 → 0.8.1

package/src/procedures/types.ts

@@ -5,11 +5,15 @@
  * Procedures are the foundation for typed RPC calls with schema validation.
  */
 
+import type { Elicit } from "./elicit.js";
+import type { ReportProgress } from "./progress.js";
+import type { ToolHintOverride } from "./hints.js";
 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";
+import type { Principal } from "../server/types.js";
 
 // =============================================================================
 // Procedure Path
@@ -83,10 +87,73 @@ export interface ProcedureMetadata {
    */
   stream?: { readonly unbounded?: boolean } | undefined;
 
+  /**
+   * The output fields that hold text from outside the host: a web page, a mail (CLI-10). The value
+   * of each field is a text, an `UntrustedText` with its source, or a list of them. A face that
+   * gives text to a model (MCP) shows these texts in envelopes: data, never instructions.
+   */
+  untrusted?: readonly string[] | undefined;
+
+  /** The short name of the procedure for people, for example the title of an MCP tool. */
+  title?: string | undefined;
+
+  /**
+   * The override of the tool hints of the effects (CLI-10). It can only make the tool look more
+   * dangerous: `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`,
+   * `openWorldHint: true`. The registry refuses each other value.
+   */
+  toolHints?: ToolHintOverride | undefined;
+
+  /**
+   * The rules of the procedure under a root of the files (roadmap R33): the inputs that name a
+   * path, or the reason that a root cannot confine it. A host with a root (`--fs-root`,
+   * `MCP_FS_ROOT`) reads them. Without the rules, the host decides from `effects`.
+   */
+  fsRoot?: FsRootRules | undefined;
+
   /** Custom metadata fields */
   [key: string]: unknown;
 }
 
+/**
+ * The rules of a procedure under a root of the files (roadmap R33). A host with a root keeps each
+ * path of these inputs in the root, or it refuses the procedure. `confineToRoot()` of
+ * `@procedures/fs` applies the rules. Without a root, the rules change nothing.
+ */
+export interface FsRootRules {
+  /**
+   * The input that names the working folder. When the call gives no value, the procedure gets the
+   * root. A relative value starts at the root.
+   */
+  readonly cwd?: string;
+  /**
+   * The inputs that name a file or a folder: a text, or a list of texts. A relative path starts at
+   * the root. The procedure gets the absolute path.
+   */
+  readonly paths?: readonly string[];
+  /**
+   * The inputs that name a file or a folder relative to the working folder, for example the files
+   * of an archive. A relative name starts at the working folder, or at the root without `cwd`.
+   * The host examines each path, and it does not change the value.
+   */
+  readonly names?: readonly string[];
+  /**
+   * The inputs of `paths` whose default is outside the working folder. Under a root, a call
+   * without a value of such an input is refused.
+   */
+  readonly required?: readonly string[];
+  /** The values of the inputs that are not paths, for example `:memory:` of SQLite. */
+  readonly values?: readonly string[];
+  /** The reason that a root cannot confine the procedure. Under a root, the host refuses it. */
+  readonly refuse?: string;
+  /**
+   * True for a procedure that starts the program of its input (`shell.run`). Under a root, the
+   * host refuses a call of a client. It accepts the nested call of a confined procedure that
+   * names this procedure in `metadata.calls`.
+   */
+  readonly program?: boolean;
+}
+
 // =============================================================================
 // Capabilities (CAPABILITIES-2026-10)
 // =============================================================================
@@ -283,6 +350,20 @@ export interface ProcedureContext {
    */
   onRef?: ((event: HydrationEvent) => void) | undefined;
 
+  /**
+   * The function that asks the person at the caller for input or a confirmation (CLI-12): MCP
+   * elicitation, or another face that can ask. Absent when no one can answer. The helpers
+   * `elicitInput` and `elicitConfirmation` then give the action `unavailable`. The nested calls
+   * get the same function.
+   */
+  elicit?: Elicit | undefined;
+
+  /**
+   * The function that tells the caller the progress of this call (an MCP progress notification).
+   * Absent when the caller asked for no progress. Only the call of the host gets it.
+   */
+  progress?: ReportProgress | undefined;
+
   /**
    * The capability of this invocation (CAPABILITIES-2026-10): its clearance, permitted effects
    * and deadline. The nested calls of `ctx.client` get it, or a narrower one. Frozen.
@@ -294,6 +375,27 @@ export interface ProcedureContext {
    * database for a lower clearance, for example. Empty when the host gives none.
    */
   resources: ResourcesOf;
+
+  /**
+   * The procedure whose handler made this call through its `ctx.client`. A call of a host or a
+   * client has no caller. The framework sets it from the invocation, so an input cannot change
+   * it. The root of the files reads it (roadmap R33).
+   */
+  caller?: AnyProcedure | undefined;
+
+  /**
+   * The principal of the call: who sends it. The server sets it from its authentication (the
+   * token, the request hook `principalOf`, `authenticate`). The nested calls get the same
+   * principal. An input or the metadata cannot change it. A call from this process has none.
+   */
+  principal?: Principal | undefined;
+
+  /**
+   * The output filter of the host for this call: its `admitItem`, with this invocation (roadmap
+   * CLI-15). A handler that sends the data of other writers later, for example a subscription,
+   * examines each row with it. Absent for a nested call, or when the host has no filter.
+   */
+  admit?: ((item: unknown) => Promise<boolean>) | undefined;
 }
 
 /**

package/src/procedures/untrusted.ts

@@ -0,0 +1,50 @@
+/**
+ * The text from outside a host: a web page, a mail, a file of a user (CLI-10).
+ *
+ * A procedure that gives such text declares the fields of its output that hold it
+ * (`metadata.untrusted`). A face that gives text to a model (MCP) then shows that text apart from
+ * the data. Envelopes tell the model that this text is data, not instructions. Another face gives
+ * the output as it is.
+ */
+
+import type { AnyProcedure } from "./types.js";
+
+/** The values of the source of a text: the attributes of its envelope. */
+export type UntrustedSource = Readonly<Record<string, string | number | boolean | null | undefined>>;
+
+/** A text from outside the host, with its source: for example the URL and the date of a page. */
+export interface UntrustedText {
+  readonly text: string;
+  readonly source?: UntrustedSource | undefined;
+}
+
+/**
+ * The value of an untrusted field of an output: a text, a text with its source, or a list of
+ * them.
+ */
+export type UntrustedValue = string | UntrustedText | readonly (string | UntrustedText)[];
+
+/** This function gives a text with its source, for an untrusted field of an output. */
+export function untrustedText(text: string, source?: UntrustedSource): UntrustedText {
+  return source === undefined ? { text } : { text, source };
+}
+
+/** The names of the output fields that hold untrusted text (`metadata.untrusted`). Empty: none. */
+export function untrustedFieldsOf(procedure: AnyProcedure): readonly string[] {
+  const fields = (procedure.metadata as { untrusted?: unknown } | undefined)?.untrusted;
+  return Array.isArray(fields) ? fields.filter((field): field is string => typeof field === "string") : [];
+}
+
+/** The texts of the value of an untrusted field, each with its source. Another value gives none. */
+export function untrustedTextsOf(value: unknown): UntrustedText[] {
+  const one = (item: unknown): UntrustedText | undefined => {
+    if (typeof item === "string") return { text: item };
+    if (item !== null && typeof item === "object" && typeof (item as { text?: unknown }).text === "string") {
+      const { text, source } = item as { text: string; source?: unknown };
+      return source !== null && typeof source === "object" ? { text, source: source as UntrustedSource } : { text };
+    }
+    return undefined;
+  };
+  const items = Array.isArray(value) ? value : [value];
+  return items.map(one).filter((item): item is UntrustedText => item !== undefined);
+}

package/src/protocol.ts

@@ -47,7 +47,8 @@ export type ProtocolErrorCode =
   | "UNAVAILABLE"
   | "CONNECTION_CLOSED"
   | "CONNECTION_NOT_FOUND"
-  | "TOPIC_NOT_FOUND";
+  | "TOPIC_NOT_FOUND"
+  | "TOPIC_CLEARED";
 
 /**
  * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
@@ -78,6 +79,7 @@ export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
   CONNECTION_CLOSED: { http: 503, retryable: true, meaning: "The connection closed before the call left" },
   CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
   TOPIC_NOT_FOUND: { http: 404, retryable: false, meaning: "The topic rule of the host has no topic with this name" },
+  TOPIC_CLEARED: { http: 410, retryable: false, meaning: "The host cleared a topic of the subscription: clear() of its bus removed the listener" },
 };
 
 /** True when a code is an error code of the protocol. */

package/src/server/browser-guard.ts

@@ -15,6 +15,9 @@
  *   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.
+ * - A request with ambient credentials (the cookies that a browser sends by itself) is trusted
+ *   only from a named origin. `"*"` does not open the origin check for it (CSRF). A list or a
+ *   function of origins still does.
  */
 
 import type { IncomingHttpHeaders } from "node:http";
@@ -74,8 +77,9 @@ export function hostNameOf(header: string | undefined): string {
   return (header.split(":")[0] ?? "").toLowerCase();
 }
 
-function originAllowedBy(origin: string, allowed: BrowserGuardOptions["allowedOrigins"]): boolean {
-  if (allowed === "*") return true;
+function originAllowedBy(origin: string, allowed: BrowserGuardOptions["allowedOrigins"], ambient: boolean): boolean {
+  // "*" names no origin: ambient credentials are not trusted from it
+  if (allowed === "*") return !ambient;
   if (typeof allowed === "function") return allowed(origin);
   return (allowed ?? []).includes(origin);
 }
@@ -102,14 +106,52 @@ function hasBody(headers: IncomingHttpHeaders): boolean {
   return length > 0 || headers["transfer-encoding"] !== undefined;
 }
 
+/**
+ * True when a request carries ambient credentials: a `Cookie` header, which a browser sends by
+ * itself, also for a request that another site starts.
+ */
+export function hasAmbientCredentials(headers: IncomingHttpHeaders): boolean {
+  const cookie = headers.cookie;
+  return typeof cookie === "string" && cookie.trim() !== "";
+}
+
+/**
+ * True when a face trusts a request only from a named origin. This is so when the server reads
+ * cookies for each request (`"always"`), or when the request carries a cookie that an auth path can
+ * read. `cookiesNamed` is true for a face that trusts no cookie from
+ * an origin that is not named, with or without an auth path.
+ *
+ * @internal
+ */
+export function needsNamedOrigin(mode: "always" | "cookies" | undefined, headers: IncomingHttpHeaders, cookiesNamed: boolean): boolean {
+  return mode === "always" || (hasAmbientCredentials(headers) && (cookiesNamed || mode !== undefined));
+}
+
+/**
+ * This function refuses a face whose server reads cookies for each request (`principalOf`) while
+ * its browser checks permit each origin (`"*"`). Each site could then send a request with the cookies
+ * of the user (CSRF).
+ *
+ * @internal
+ */
+export function assertNamedOrigins(face: string, mode: "always" | "cookies" | undefined, allowedOrigins: BrowserGuardOptions["allowedOrigins"], originOption: string): void {
+  if (mode !== "always" || allowedOrigins !== "*") return;
+  throw new Error(
+    `${face}: the request hook principalOf reads the cookies of each request, and the origin "*" lets each site send them (CSRF). Give ${originOption} or allowedOrigins a list or a function of the origins that can call.`
+  );
+}
+
 /**
  * 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.
+ * `http` adds the checks of the method and the body. `ambient` is true when the server can trust
+ * ambient credentials (cookies) for the request. Then `"*"` does not permit another origin. Only a
+ * named origin (a list or a function) does.
  */
 export function checkBrowserRequest(
   req: GuardedRequest,
   options: BrowserGuardOptions = {},
-  http = false
+  http = false,
+  ambient = false
 ): GuardResult {
   const { headers } = req;
 
@@ -123,12 +165,12 @@ export function checkBrowserRequest(
 
   const origin = typeof headers.origin === "string" ? headers.origin : undefined;
   if (origin !== undefined) {
-    if (!sameOrigin(origin, headers.host) && !originAllowedBy(origin, options.allowedOrigins)) {
+    if (!sameOrigin(origin, headers.host) && !originAllowedBy(origin, options.allowedOrigins, ambient)) {
       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 !== "*") {
+    if ((site === "cross-site" || site === "same-site") && (options.allowedOrigins !== "*" || ambient)) {
       return { ok: false, status: 403, code: "FORBIDDEN_ORIGIN", message: "Forbidden: a request from another site" };
     }
   }

package/src/server/host-policy.ts

@@ -12,6 +12,8 @@
  *   procedures (a host for an outside caller sets it).
  * - `timeout`: 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).
+ * - `principalOf`: the request hook. It reads the credentials of a network request (a cookie, a
+ *   header, the query) and gives a bearer token, a principal and a narrowing.
  * - `capability`, `readOnly`, `clearanceOrder`, `resources`, `admitItem`: the capability of each
  *   call and what the host gives for it (CAPABILITIES-2026-10).
  * - `events`: the remote events of the host (`documentation/EVENTS.md`). The server pins
@@ -21,7 +23,7 @@
 import type { Capability, ClearanceOrder, ProcedurePath, ResourcesOf } from "../procedures/types.js";
 import type { AdmitItem, Interceptor, Invocation } from "../procedures/invoke.js";
 import { narrowCapability } from "../procedures/capability.js";
-import type { ServerRequest } from "./types.js";
+import type { PrincipalOf, ServerRequest } from "./types.js";
 import { timeoutInterceptor } from "../procedures/interceptors.js";
 import type { BrowserGuardOptions } from "./browser-guard.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
@@ -73,6 +75,11 @@ export interface HostPolicyOptions {
   interceptors?: readonly Interceptor[] | undefined;
   /** The token that each network request must send (HTTP and WebSocket transports). */
   token?: string | undefined;
+  /**
+   * The request hook: it reads the credentials of each network request (a cookie, a header, the
+   * query) and gives a bearer token, a principal and a narrowing (`ProcedureServerOptions`).
+   */
+  principalOf?: PrincipalOf | undefined;
   /** The browser checks of the network transports (`allowedOrigins`, `allowedHosts`, `allowGet`). */
   browser?: BrowserGuardOptions | undefined;
   /**
@@ -103,6 +110,8 @@ export interface HostPolicy {
   readonly strictCalls: boolean;
   readonly interceptors: readonly Interceptor[];
   readonly token: string | undefined;
+  /** The request hook of the network requests, or undefined for none. */
+  readonly principalOf?: PrincipalOf | 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;
@@ -151,6 +160,7 @@ export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
     strictCalls: options.strictCalls ?? false,
     interceptors,
     token: options.token,
+    ...(options.principalOf ? { principalOf: options.principalOf } : {}),
     browser: options.browser ?? {},
     capabilityOf: capabilityOfOptions(options),
     clearanceOrder: options.clearanceOrder,
@@ -169,6 +179,8 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     strictCalls: policy.strictCalls,
     // The token of the policy: ProcedureServer examines it for each network request (R18)
     ...(policy.token !== undefined ? { token: policy.token } : {}),
+    // The request hook of the policy: the credentials of a cookie, a header or the query (CLI-2a)
+    ...(policy.principalOf ? { principalOf: policy.principalOf } : {}),
     ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
     ...(policy.capabilityOf ? { capability: policy.capabilityOf } : {}),
     ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),

package/src/server/index.ts

@@ -48,6 +48,9 @@ export {
   type RequestHandler,
   type Credentials,
   type Principal,
+  type PrincipalOf,
+  type RequestIdentity,
+  type AmbientCredentials,
   type ServerHandler,
   type ServerMiddleware,
   type ServerContext,