@procedures/client 0.8.0 → 0.9.0

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,6 +87,23 @@ 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`,
@@ -238,6 +259,22 @@ export interface RepositoryProvider {
    */
   getStorage<T>(collection: string): CollectionStorage<T>;
 
+  /**
+   * The storage of one partition of a collection (roadmap CLI-17), for example the items of one
+   * tenant. A repository without this method has no partitions: the collection procedures then
+   * refuse a call with a partition, and never give it the storage of all partitions.
+   */
+  getPartitionStorage?<T>(collection: string, partition: string): CollectionStorage<T>;
+
+  /** True when the collection has partitions (roadmap CLI-17). Then a call resolves its partition with `resolvePartition`. */
+  hasPartitions?(collection: string): boolean;
+
+  /**
+   * The partition of a call to a partitioned collection (roadmap CLI-17): from the context (the
+   * tenant of `ctx.principal`) and the partition that the call asks for. `null` refuses the call.
+   */
+  resolvePartition?(collection: string, ctx: ProcedureContext, requested: string | undefined): string | undefined | null | Promise<string | undefined | null>;
+
   /**
    * Check if a collection exists.
    *
@@ -329,6 +366,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.
@@ -347,6 +398,20 @@ export interface ProcedureContext {
    * 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/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,

package/src/server/procedure-server.ts

@@ -6,7 +6,7 @@
  */
 
 import { Server, type ServerOptions } from "./server.js";
-import type { Method, Principal, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
+import type { AmbientCredentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import type {
   AnyProcedure,
@@ -18,8 +18,9 @@ import { pathToKey } from "../procedures/types.js";
 import { ProcedureRegistry, PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { createCollectionProcedures } from "../procedures/collection/procedures.js";
 import { InvocationError, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
-import type { Capability, ClearanceOrder, ResourcesOf } from "../procedures/types.js";
-import { TIMEOUT_METADATA_KEY, effectsOf, narrowCapability } from "../procedures/capability.js";
+import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
+import type { CollectionPartitions } from "../procedures/collection/partition.js";
+import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
 import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
@@ -28,6 +29,7 @@ import { realClock, type Clock } from "../clock.js";
 import { errorCodeOf } from "../protocol.js";
 import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
 import { getGlobalEventBus } from "../events/bus.js";
+import type { CollectionProceduresOptions } from "../procedures/collection/procedures.js";
 
 // =============================================================================
 // Types
@@ -139,6 +141,24 @@ export interface ProcedureServerOptions extends ServerOptions {
    */
   authenticate?: ((request: ServerRequest<unknown>) => Principal | undefined | Promise<Principal | undefined>) | undefined;
 
+  /**
+   * The request hook of the server: it reads the credentials of each network request (a cookie, a
+   * header, the query) and gives a bearer token, a principal and a narrowing. It runs before the
+   * token check: its bearer token replaces the bearer token of the credentials. Its principal
+   * replaces the principal of the token check. `authenticate` runs after it and can read
+   * `request.principal`. Undefined or an error refuses the request with `UNAUTHORIZED`. A request
+   * without credentials (from this process) does not go through the hook.
+   */
+  principalOf?: PrincipalOf | undefined;
+
+  /**
+   * How the server can authenticate a request with ambient credentials (cookies), for the CSRF
+   * checks of the network faces. The default is `"always"` with `principalOf`, `"cookies"` with
+   * `authenticate`, and none without them. `false`: the server reads no cookies, for example an
+   * `authenticate` function that reads only the bearer token.
+   */
+  ambientCredentials?: AmbientCredentials | false | undefined;
+
   /**
    * The remote events of the server (`documentation/EVENTS.md`): a bus and its topic rule, or an
    * `EventPublisher`. The server pins the procedure `events.subscribe`, outside its registry, so a
@@ -297,6 +317,8 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
 export class ProcedureServer extends Server implements RepositoryProvider {
   private readonly procedureRegistry: ProcedureRegistry;
   private readonly storages = new Map<string, CollectionStorage<unknown>>();
+  /** The partitions of each partitioned collection: their storages and their resolver (roadmap CLI-17) */
+  private readonly partitions = new Map<string, CollectionPartitions<unknown>>();
   /** For each storage: the calls in flight that took it, and the closes that wait for them */
   private readonly storageUses = new Map<CollectionStorage<unknown>, { calls: number; waiters: Array<() => void> }>();
   /** The clock of the wait of `useStorage` */
@@ -326,13 +348,19 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   private draining = false;
   /** The calls in flight, a stream until its end */
   private inFlight = 0;
-  /** The token of the server, and its authenticate function (R18) */
+  /** The token of the server, its request hook and its authenticate function (R18) */
   private readonly token: string | undefined;
+  private readonly principalOf: PrincipalOf | undefined;
   private readonly authenticate: ProcedureServerOptions["authenticate"];
   /** The functions that `stop()` waits on: each one runs when no call is in flight */
   private idleWaiters: Array<() => void> = [];
   /** The publisher of the remote events, from the option `events`, or undefined. */
   readonly publisher: EventPublisher | undefined;
+  /**
+   * How the server can authenticate a request with ambient credentials (cookies). The network faces
+   * read it: they trust such a request only from a named origin (CSRF).
+   */
+  readonly ambientCredentials: AmbientCredentials | undefined;
 
   constructor(options: ProcedureServerOptions = {}) {
     super(options);
@@ -350,7 +378,10 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     };
     this.idempotency = options.idempotency === false ? undefined : new IdempotencyCache(options.idempotency ?? {});
     this.token = options.token;
+    this.principalOf = options.principalOf;
     this.authenticate = options.authenticate;
+    const ambient = options.ambientCredentials ?? (this.principalOf ? "always" : this.authenticate ? "cookies" : undefined);
+    this.ambientCredentials = ambient === false ? undefined : ambient;
     // The remote events: the server pins events.subscribe, as it pins host.health (EVENTS.md)
     this.publisher = options.events instanceof EventPublisher ? options.events : options.events ? new EventPublisher(options.events) : undefined;
     if (this.publisher) this.registerProcedure(this.publisher.procedure);
@@ -393,7 +424,54 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    * @param collection - Collection name
    */
   hasCollection(collection: string): boolean {
-    return this.storages.has(collection);
+    return this.storages.has(collection) || this.partitions.has(collection);
+  }
+
+  /**
+   * The storage of one partition of a collection (roadmap CLI-17).
+   *
+   * @throws Error if the collection has no partitions
+   */
+  getPartitionStorage<T>(collection: string, partition: string): CollectionStorage<T> {
+    const partitions = this.partitions.get(collection);
+    if (!partitions) {
+      throw new Error(`Collection has no partitions: ${collection}`);
+    }
+    return partitions.storageOf(partition) as CollectionStorage<T>;
+  }
+
+  /** True when the collection has partitions (roadmap CLI-17). */
+  hasPartitions(collection: string): boolean {
+    return this.partitions.has(collection);
+  }
+
+  /**
+   * The partition of a call to a partitioned collection (roadmap CLI-17), from the resolver of
+   * `usePartitions`. `null` refuses the call.
+   *
+   * @throws Error if the collection has no partitions
+   */
+  resolvePartition(collection: string, ctx: ProcedureContext, requested: string | undefined): string | undefined | null | Promise<string | undefined | null> {
+    const partitions = this.partitions.get(collection);
+    if (!partitions) {
+      throw new Error(`Collection has no partitions: ${collection}`);
+    }
+    return partitions.resolve(ctx, requested);
+  }
+
+  /**
+   * Configure the partitions of a collection (roadmap CLI-17). `resolve` gives the partition of
+   * each call from its context (the tenant of `ctx.principal`) and the partition that the call asks
+   * for: the collection procedures and the subscriptions of `EventPublisher` use it. `storageOf`
+   * gives the storage of a partition: give the same storage for the same partition each time.
+   *
+   * @param name - Collection name
+   * @param partitions - The storage of each partition, and the resolver
+   * @returns this (for chaining)
+   */
+  usePartitions<T>(name: string, partitions: CollectionPartitions<T>): this {
+    this.partitions.set(name, partitions as CollectionPartitions<unknown>);
+    return this;
   }
 
   // ===========================================================================
@@ -475,17 +553,20 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   private callRepository(): { repository: RepositoryProvider; release: () => void } {
     const taken = new Set<CollectionStorage<unknown>>();
     let released = false;
+    const take = <T>(storage: CollectionStorage<unknown>): CollectionStorage<T> => {
+      if (!released && !taken.has(storage)) {
+        taken.add(storage);
+        const use = this.storageUses.get(storage) ?? { calls: 0, waiters: [] };
+        use.calls++;
+        this.storageUses.set(storage, use);
+      }
+      return storage as CollectionStorage<T>;
+    };
     const repository: RepositoryProvider = {
-      getStorage: <T>(collection: string): CollectionStorage<T> => {
-        const storage = this.getStorage<unknown>(collection);
-        if (!released && !taken.has(storage)) {
-          taken.add(storage);
-          const use = this.storageUses.get(storage) ?? { calls: 0, waiters: [] };
-          use.calls++;
-          this.storageUses.set(storage, use);
-        }
-        return storage as CollectionStorage<T>;
-      },
+      getStorage: <T>(collection: string): CollectionStorage<T> => take<T>(this.getStorage<unknown>(collection)),
+      getPartitionStorage: <T>(collection: string, partition: string): CollectionStorage<T> => take<T>(this.getPartitionStorage<unknown>(collection, partition)),
+      hasPartitions: (collection: string): boolean => this.hasPartitions(collection),
+      resolvePartition: (collection: string, ctx: ProcedureContext, requested: string | undefined) => this.resolvePartition(collection, ctx, requested),
       hasCollection: (collection: string): boolean => this.hasCollection(collection),
     };
     const release = (): void => {
@@ -642,9 +723,11 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   }
 
   /**
-   * The token check and the principal of a request (roadmap R18). A network request (with
-   * credentials) must present the token. The authenticate function gives the principal. The
-   * function gives an UNAUTHORIZED response, or undefined when the request passes.
+   * The token check and the principal of a request (roadmap R18). The request hook reads the
+   * credentials of a network request first: a bearer token, a principal and a narrowing. A
+   * network request (with credentials) must present the token. The authenticate function gives
+   * the principal. The function gives an UNAUTHORIZED response, or undefined when the request
+   * passes.
    */
   private async admit(request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
     const unauthorized = (message: string): ServerResponse<unknown> => ({
@@ -652,10 +735,26 @@ export class ProcedureServer extends Server implements RepositoryProvider {
       status: { type: "error", code: "UNAUTHORIZED", message, retryable: false },
       metadata: {},
     });
-    if (this.token !== undefined && request.credentials !== undefined) {
-      if (!tokenMatches(this.token, request.credentials.bearer)) return unauthorized("Unauthorized: this server requires its token");
+    const credentials = request.credentials;
+    let identity: RequestIdentity | undefined;
+    if (this.principalOf && credentials !== undefined) {
+      try {
+        identity = await this.principalOf(credentials, request);
+      } catch {
+        identity = undefined;
+      }
+      if (!identity) return unauthorized("Unauthorized: the server did not accept the credentials");
+    }
+    if (this.token !== undefined && credentials !== undefined) {
+      const bearer = identity?.bearer ?? credentials.bearer;
+      if (!tokenMatches(this.token, bearer)) return unauthorized("Unauthorized: this server requires its token");
       request.principal = { id: "token", via: "token" };
     }
+    if (identity?.principal) request.principal = identity.principal;
+    if (identity?.narrowing) {
+      const order = this.capabilityOptions.clearanceOrder;
+      request.narrowing = request.narrowing ? joinNarrowing(request.narrowing, identity.narrowing, order) : identity.narrowing;
+    }
     if (this.authenticate) {
       let principal: Principal | undefined;
       try {
@@ -734,6 +833,17 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     return { ...response, id: request.id };
   }
 
+  /**
+   * The capability of a request. It comes from the server, never from the request. The remaining
+   * time of the caller and the narrowing of the request can only make it narrower
+   * (CAPABILITIES-2026-10, decision 9). Two different clearances without an order throw.
+   */
+  private capabilityOf(request: ServerRequest<unknown>): Capability | undefined {
+    const { capability, clearanceOrder } = this.capabilityOptions;
+    const base = withRequestTimeout(typeof capability === "function" ? capability(request) : capability, request, clearanceOrder);
+    return request.narrowing ? narrowCapability(base, request.narrowing, clearanceOrder) : base;
+  }
+
   /** Run a procedure for a request with a signal. */
   private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): Promise<ServerResponse<unknown>> {
     // The call uses the storages that it takes until its end: the end of a stream, for a stream
@@ -742,21 +852,31 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     try {
       // One invocation path for every host (ARCHITECTURE-PROPOSALS P1): input validation, the
       // context, the expose rule for nested calls (BUGS-2026-07 H18) and output validation
-      const { capability, clearanceOrder, resources, admitItem } = this.capabilityOptions;
+      const { clearanceOrder, resources, admitItem } = this.capabilityOptions;
+      let capability: Capability | undefined;
+      try {
+        capability = this.capabilityOf(request);
+      } catch (error) {
+        const message = `The server cannot narrow the capability of the request: ${error instanceof Error ? error.message : String(error)}`;
+        return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+      }
       const output = await invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
         metadata: request.metadata,
         signal,
+        // What the face of the call offers: it asks the person, and it shows the progress (CLI-12)
+        ...(request.elicit ? { elicit: request.elicit } : {}),
+        ...(request.progress ? { progress: request.progress } : {}),
         repository,
         expose: this.expose,
         strictCalls: this.strictCalls,
         interceptors: this.interceptors,
-        // The capability comes from the server, never from the request. The remaining time of
-        // the caller can only make the deadline earlier (CAPABILITIES-2026-10, decision 9).
-        capability: withRequestTimeout(typeof capability === "function" ? capability(request) : capability, request, clearanceOrder),
+        capability,
         clearanceOrder,
         resources,
         admitItem,
+        // The principal of the authentication: ctx.principal, and the nested calls (R18)
+        ...(request.principal !== undefined ? { principal: request.principal } : {}),
         // The bus of the remote events is the bus of the procedures (EVENTS.md)
         ...(this.publisher ? { bus: this.publisher.bus } : {}),
       });
@@ -784,11 +904,12 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    * Creates standard CRUD procedures using the configured storage.
    *
    * @param collectionName - Collection name
+   * @param options - The query policy of `find`. `$regex` is off unless the policy permits it.
    */
-  registerCollectionProcedures(collectionName: string): void {
+  registerCollectionProcedures(collectionName: string, options?: CollectionProceduresOptions): void {
     // Uses a top-level import; require() is not available in this ESM package and
     // previously threw "Cannot find module" on every call. See BUGS-2026-07 H13.
-    const procedures = createCollectionProcedures(collectionName);
+    const procedures = createCollectionProcedures(collectionName, options);
 
     // Register with the procedure registry first
     this.procedureRegistry.registerAll(procedures);