@procedures/client 0.7.0 → 0.8.1

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,
@@ -19,14 +19,16 @@ 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 { 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";
 import { TIMER_DEFAULTS } from "../timers.js";
+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
@@ -49,8 +51,18 @@ export interface UseStorageOptions {
    * flush fails, the old storage stays and `useStorage` throws.
    */
   drain?: boolean | undefined;
-  /** True: the server closes the old storage after the change. */
+  /**
+   * True: the server closes the old storage after the change. The close waits for the calls that
+   * took the old storage, for the time of `grace` at most.
+   */
   close?: boolean | undefined;
+  /**
+   * The longest time that the close waits for the calls on the old storage, for example
+   * `seconds(5)`. When the time ends, the server closes the old storage. A call that still uses it
+   * then fails with the error of a closed storage. 0: the server closes it at once.
+   * @default 30 seconds (`TIMER_DEFAULTS.server.storageGraceMs`)
+   */
+  grace?: Duration | undefined;
 }
 
 /**
@@ -66,6 +78,12 @@ export interface ProcedureServerOptions extends ServerOptions {
   /** Collections to configure with storage backends */
   collections?: Record<string, CollectionStorage<unknown>>;
 
+  /**
+   * The clock of the wait of `useStorage` for the calls on an old storage (roadmap R35). The
+   * default is the clock of the platform. A test gives a fake clock.
+   */
+  clock?: Clock | undefined;
+
   /**
    * The procedures that the callers of this server can reach. `registerFromRegistry()` registers
    * only these procedures. A data-driven procedure (control flow, `eval`, a procedure that
@@ -122,6 +140,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
@@ -166,6 +202,15 @@ export interface StopOptions {
   grace?: Duration | undefined;
 }
 
+/** The items of a stream. At the end of the stream, or when its reader stops, `release` runs. */
+async function* releasedAtEnd<T>(items: AsyncIterable<T>, release: () => void): AsyncGenerator<T, void, undefined> {
+  try {
+    yield* items;
+  } finally {
+    release();
+  }
+}
+
 /** A signal that aborts when one of the signals aborts. */
 function joinSignals(first: AbortSignal | undefined, second: AbortSignal): AbortSignal {
   if (!first) return second;
@@ -271,6 +316,10 @@ 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>>();
+  /** 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` */
+  private readonly clock: Clock;
   /** The procedures that `registerProcedure` pinned, by key */
   private readonly pinnedProcedures = new Map<string, AnyProcedure>();
   /**
@@ -296,18 +345,25 @@ 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);
 
     this.procedureRegistry = options.registry ?? PROCEDURE_REGISTRY;
+    this.clock = options.clock ?? realClock;
     this.expose = options.expose;
     this.strictCalls = options.strictCalls ?? false;
     this.interceptors = options.interceptors ?? [];
@@ -319,7 +375,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);
@@ -379,7 +438,11 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    *   failed flush keeps the old storage and throws. A call that arrives during the flush goes
    *   to the old storage.
    * - `close`: the server closes the old storage after the change. The close of a
-   *   `HybridStorage` sends the writes that arrived during the flush.
+   *   `HybridStorage` sends the writes that arrived during the flush. An old storage that another
+   *   collection still uses stays open: the server closes it when the last collection leaves it.
+   * - The new calls use the new storage at once. Before the close, the server waits for the calls
+   *   that took the old storage, for the time of `grace` at most. Before, such a call could fail
+   *   because the storage was closed.
    *
    * @param name - Collection name
    * @param storage - Storage backend
@@ -396,20 +459,76 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     return this.replaceStorage(name, storage as CollectionStorage<unknown>, options);
   }
 
-  /** The change of `useStorage` with options: flush the old storage, change, close the old one. */
+  /**
+   * The change of `useStorage` with options: flush the old storage, change, wait for the calls on
+   * the old storage, and close it.
+   */
   private async replaceStorage(name: string, storage: CollectionStorage<unknown>, options: UseStorageOptions): Promise<this> {
+    const graceMs = optionalMs(options.grace, "grace") ?? TIMER_DEFAULTS.server.storageGraceMs;
     const old = this.storages.get(name);
     const other = old !== undefined && old !== storage ? old : undefined;
     if (other && options.drain) {
       await other.flush?.();
     }
     this.storages.set(name, storage);
-    if (other && options.close) {
+    // Another collection that uses the same storage keeps it open. Before, the close broke the
+    // calls of that collection (tracker O31).
+    if (other && options.close && ![...this.storages.values()].includes(other)) {
+      await this.callsOnStorageEnded(other, graceMs);
       await other.close();
     }
     return this;
   }
 
+  /** A promise that resolves when no call uses the storage, or when `graceMs` ends. */
+  private callsOnStorageEnded(storage: CollectionStorage<unknown>, graceMs: number): Promise<void> {
+    const use = this.storageUses.get(storage);
+    if (!use || graceMs <= 0) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      const done = (): void => {
+        cancel();
+        const index = use.waiters.indexOf(done);
+        if (index >= 0) use.waiters.splice(index, 1);
+        resolve();
+      };
+      const cancel = this.clock.after(graceMs, done);
+      use.waiters.push(done);
+    });
+  }
+
+  /**
+   * The repository of one call. The call is a user of each storage that it takes, until
+   * `release()`. Then a close of `useStorage` can go on.
+   */
+  private callRepository(): { repository: RepositoryProvider; release: () => void } {
+    const taken = new Set<CollectionStorage<unknown>>();
+    let released = false;
+    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>;
+      },
+      hasCollection: (collection: string): boolean => this.hasCollection(collection),
+    };
+    const release = (): void => {
+      if (released) return;
+      released = true;
+      for (const storage of taken) {
+        const use = this.storageUses.get(storage);
+        if (!use || --use.calls > 0) continue;
+        this.storageUses.delete(storage);
+        for (const waiter of use.waiters.slice()) waiter();
+      }
+    };
+    return { repository, release };
+  }
+
   /**
    * Configure multiple storages at once.
    *
@@ -551,9 +670,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> => ({
@@ -561,10 +682,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 {
@@ -643,42 +780,69 @@ 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
+    const { repository, release } = this.callRepository();
+    let streams = false;
     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,
-        repository: this,
+        // 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 } : {}),
       });
       if (output.kind === "stream") {
         // The faces that collect a stream read this mark (roadmap R15)
         const unbounded = (procedure.metadata as { stream?: { unbounded?: boolean } } | undefined)?.stream?.unbounded === true;
+        streams = true;
         return {
           id: request.id,
           status: { type: "success", code: 200 },
-          stream: output.items,
+          stream: releasedAtEnd(output.items, release),
           metadata: unbounded ? { [STREAM_METADATA_KEY]: "unbounded" } : {},
         };
       }
       return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
     } catch (error) {
       return errorResponse(request.id, error);
+    } finally {
+      if (!streams) release();
     }
   }
 
@@ -687,11 +851,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);

package/src/server/request-auth.ts

@@ -1,19 +1,41 @@
 /**
  * The credentials of a network request (roadmap R18). A server transport reads them into
- * `ServerRequest.credentials`, and leaves the secret headers out of the metadata, so a handler
- * and a nested call do not see them. `ProcedureServer` examines them.
+ * `ServerRequest.credentials`. It leaves the secret headers out of the metadata, so a handler and a
+ * nested call do not see them. `ProcedureServer` examines them.
+ *
+ * This module imports no Node code: a server in a browser or a worker can use it too.
  */
 
 import type { Credentials } from "./types.js";
 
 /** The headers that carry a secret. They do not go into the metadata of a request. */
-const SECRET_HEADERS = new Set(["authorization", "proxy-authorization", "cookie", "x-api-key"]);
+const SECRET_HEADERS: ReadonlySet<string> = new Set(["authorization", "proxy-authorization", "cookie", "x-api-key"]);
 
-/** The headers without the secret ones, and without the headers that are not text. */
-export function withoutSecretHeaders(headers: Record<string, unknown>): Record<string, string> {
+/**
+ * True when a header carries a secret: a header of the default list (`Authorization`,
+ * `Proxy-Authorization`, `Cookie`, `X-Api-Key`), or a header of `more`. The names are lower case.
+ */
+export function isSecretHeader(name: string, more?: ReadonlySet<string>): boolean {
+  const key = name.toLowerCase();
+  return SECRET_HEADERS.has(key) || (more?.has(key) ?? false);
+}
+
+/** This function gives a set of lower-case header names. */
+export function headerNames(names: Iterable<string> | undefined): ReadonlySet<string> {
+  const set = new Set<string>();
+  for (const name of names ?? []) set.add(name.toLowerCase());
+  return set;
+}
+
+/**
+ * The headers without the secret ones, and without the headers that are not text. `secret` names
+ * more headers that carry a secret, for example the token header of an application.
+ */
+export function withoutSecretHeaders(headers: Record<string, unknown>, secret?: Iterable<string>): Record<string, string> {
+  const more = secret === undefined ? undefined : headerNames(secret);
   const out: Record<string, string> = {};
   for (const [key, value] of Object.entries(headers)) {
-    if (!SECRET_HEADERS.has(key.toLowerCase()) && typeof value === "string") out[key] = value;
+    if (!isSecretHeader(key, more) && typeof value === "string") out[key] = value;
   }
   return out;
 }
@@ -33,3 +55,103 @@ export function credentialsOf(request: { headers: Record<string, unknown>; url?:
   const query = new URL(request.url ?? "/", "http://localhost").searchParams.get("token");
   return query === null ? {} : { bearer: query };
 }
+
+/** The text of a header value: a list of values becomes one text, with ", " between the values. */
+function headerText(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string").join(", ");
+  return undefined;
+}
+
+/** This function decodes a cookie value. A value that is not valid URI encoding stays as it is. */
+function decodeCookieValue(value: string): string {
+  const unquoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+  try {
+    return decodeURIComponent(unquoted);
+  } catch {
+    return unquoted;
+  }
+}
+
+/**
+ * The cookies of a `Cookie` header, by name. The function decodes each URI-encoded value when it
+ * can. When two cookies have the same name, the first one stays: a browser sends the
+ * cookie of the longest path first. A part without `=` is not a cookie.
+ */
+export function cookiesOf(header: unknown): Record<string, string> {
+  const text = Array.isArray(header) ? header.filter((item): item is string => typeof item === "string").join("; ") : header;
+  if (typeof text !== "string" || text === "") return {};
+  const cookies = new Map<string, string>();
+  for (const part of text.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (name === "" || cookies.has(name)) continue;
+    cookies.set(name, decodeCookieValue(part.slice(eq + 1).trim()));
+  }
+  // fromEntries defines own properties: a cookie named "__proto__" changes no prototype
+  return Object.fromEntries(cookies);
+}
+
+/**
+ * The parts of a request URL: its path and its query. The function does not resolve the URL
+ * against a host, so a path that starts with "//" stays a path.
+ */
+export function urlParts(url: string | undefined): { path: string; query: URLSearchParams } {
+  let raw = url ?? "/";
+  // The absolute form of a request line (a request through a proxy): the path and the query only
+  if (!raw.startsWith("/") && /^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    try {
+      const absolute = new URL(raw);
+      raw = `${absolute.pathname}${absolute.search}`;
+    } catch {
+      // Not a URL: the text stays a path
+    }
+  }
+  const mark = raw.indexOf("?");
+  return mark === -1 ? { path: raw, query: new URLSearchParams() } : { path: raw.slice(0, mark), query: new URLSearchParams(raw.slice(mark + 1)) };
+}
+
+/** The first value of each query parameter, by name. */
+export function queryRecord(query: URLSearchParams): Record<string, string> {
+  const values = new Map<string, string>();
+  for (const [key, value] of query) if (!values.has(key)) values.set(key, value);
+  return Object.fromEntries(values);
+}
+
+/** The options of `requestCredentials`. */
+export interface RequestCredentialsOptions {
+  /**
+   * The query parameter whose value is the bearer token of a request without an
+   * `Authorization: Bearer` header. A browser WebSocket cannot set headers, so the WebSocket
+   * server reads `token`. `false` reads no query parameter.
+   * @default false
+   */
+  readonly tokenQuery?: string | false | undefined;
+}
+
+/**
+ * The credentials of a network request (roadmap R18): the bearer token, the cookies, each header
+ * (the secret ones too) and the first value of each query parameter. The request hook of a server
+ * (`principalOf`) reads them. They are not in the metadata, so a handler does not see them.
+ */
+export function requestCredentials(
+  request: { headers: Record<string, unknown>; url?: string | undefined },
+  options: RequestCredentialsOptions = {}
+): Credentials {
+  const headers = new Map<string, string>();
+  for (const [key, value] of Object.entries(request.headers)) {
+    const text = headerText(value);
+    if (text !== undefined) headers.set(key.toLowerCase(), text);
+  }
+  const { query } = urlParts(request.url);
+  const fromHeader = bearerOf(headers.get("authorization"));
+  const fromQuery = options.tokenQuery ? query.get(options.tokenQuery) ?? undefined : undefined;
+  const bearer = fromHeader ?? fromQuery;
+  return {
+    ...(bearer !== undefined ? { bearer } : {}),
+    cookies: cookiesOf(headers.get("cookie")),
+    headers: Object.fromEntries(headers),
+    query: queryRecord(query),
+  };
+}

package/src/server/types.ts

@@ -5,7 +5,10 @@
  * Enables handling HTTP, WebSocket, gRPC, etc. with unified RPC format.
  */
 
+import type { Elicit } from "../procedures/elicit.js";
+import type { ReportProgress } from "../procedures/progress.js";
 import type { Metadata, Status, Method } from "../client/types.js";
+import type { CapabilityRequest } from "../procedures/types.js";
 
 // Re-export Method from client types
 export type { Method };
@@ -27,27 +30,86 @@ export interface ServerRequest<TReq = unknown> {
   /** Request metadata (headers, query params, etc.) */
   metadata: Metadata;
 
+  /**
+   * The function that asks the person at the caller, when the face can ask (MCP elicitation,
+   * CLI-12). The procedure gets it as `ctx.elicit`. It is not in the metadata, so a caller cannot
+   * send it.
+   */
+  elicit?: Elicit | undefined;
+
+  /**
+   * The function that tells the caller the progress of the call, when the caller asked for it
+   * (an MCP progress token). The procedure gets it as `ctx.progress`.
+   */
+  progress?: ReportProgress | undefined;
+
   /** Abort signal for cancellation */
   signal?: AbortSignal;
 
   /**
-   * The credentials that a network transport read from the request: the bearer token of an
-   * `Authorization` header, or of the `token` query of a WebSocket connection (roadmap R18). They
-   * are not in the metadata, so a handler and a nested call do not see them. A request without
-   * credentials comes from this process (a direct `handle()`, MCP over stdio).
+   * The credentials that a network transport read from the request (roadmap R18). They have the
+   * bearer token of an `Authorization` header, or of the `token` query of a WebSocket connection.
+   * They also have the cookies, the headers and the query of the request. They are not in the
+   * metadata, so a handler and a nested call do not see them. A request without credentials comes
+   * from this process (a direct `handle()`, MCP over stdio).
    */
   credentials?: Credentials | undefined;
 
   /** The principal of the request: who sends it. `ProcedureServer` sets it when it authenticates the request. */
   principal?: Principal | undefined;
+
+  /**
+   * A narrower capability that the request asks for. The request hook of the server
+   * (`principalOf`) can set it. The server narrows the capability of the call with it, so the
+   * capability does not become wider.
+   */
+  narrowing?: CapabilityRequest | undefined;
 }
 
-/** The credentials of a request. */
+/**
+ * The credentials of a request. A network transport sets each field that it can read. The request
+ * hook of the server (`principalOf`) reads them.
+ */
 export interface Credentials {
   /** The bearer token that the request presents. */
   readonly bearer?: string | undefined;
+  /** The cookies of the request, by name (the `Cookie` header of an HTTP request or of an upgrade). */
+  readonly cookies?: Readonly<Record<string, string>> | undefined;
+  /** Each header of the request, the secret headers too, by lower-case name. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  /** The first value of each query parameter of the request URL, by name. */
+  readonly query?: Readonly<Record<string, string>> | undefined;
+}
+
+/**
+ * What the request hook of a server (`principalOf`) gives for a network request. Each field is
+ * optional: an empty object accepts the request without a principal.
+ */
+export interface RequestIdentity {
+  /**
+   * The token to compare with the token of the server, for example the value of a cookie or of an
+   * application header. Without it, the server compares the bearer token of the credentials.
+   */
+  readonly bearer?: string | undefined;
+  /** The principal of the request. It replaces the principal of the token check. */
+  readonly principal?: Principal | undefined;
+  /**
+   * A narrower capability that the request asks for, for example a guest mode of a cookie. The
+   * server narrows the capability of the call with it. A request for more has no effect.
+   */
+  readonly narrowing?: CapabilityRequest | undefined;
 }
 
+/**
+ * The request hook of a server: it reads the credentials of a network request (a cookie, a header,
+ * the query) and gives the identity of the request. Undefined, or an error, refuses the request
+ * with `UNAUTHORIZED`. The hook runs before the token check and before `authenticate`.
+ */
+export type PrincipalOf = (
+  credentials: Credentials,
+  request: ServerRequest<unknown>
+) => RequestIdentity | undefined | Promise<RequestIdentity | undefined>;
+
 /** Who sends a request (roadmap R18). */
 export interface Principal {
   /** The id of the principal. With the token of a host: "token". */
@@ -66,8 +128,23 @@ export interface Principal {
  */
 export interface RequestHandler {
   handle(request: ServerRequest): Promise<ServerResponse>;
+  /**
+   * How the handler can authenticate a network request with ambient credentials: the cookies that
+   * a browser sends by itself, also for a request of another site (CSRF). A network face then
+   * trusts such a request only from a named origin. Absent: the handler reads no cookies.
+   */
+  readonly ambientCredentials?: AmbientCredentials | undefined;
 }
 
+/**
+ * How a server can authenticate a request with ambient credentials (cookies):
+ * - `"always"`: each network request. The request hook `principalOf` reads the cookies, so a face
+ *   trusts a request only from a named origin.
+ * - `"cookies"`: a request that carries a cookie. An `authenticate` function can read it, so a face
+ *   trusts a request with a cookie only from a named origin.
+ */
+export type AmbientCredentials = "always" | "cookies";
+
 /**
  * Server response in unified RPC format.
  * Converted by transport adapters to protocol-specific responses.