@procedures/client 0.8.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,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`,
@@ -329,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.
@@ -347,6 +382,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,
@@ -19,7 +19,7 @@ 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";
@@ -28,6 +28,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 +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
@@ -326,13 +345,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 +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);
@@ -642,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> => ({
@@ -652,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 {
@@ -734,6 +780,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 +799,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 +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),
+  };
+}