@procedures/client 0.8.0 → 0.8.1

package/dist/server/request-auth.js

@@ -1,15 +1,36 @@
 /**
  * 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.
  */
 /** 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"]);
-/** The headers without the secret ones, and without the headers that are not text. */
-export function withoutSecretHeaders(headers) {
+/**
+ * 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, more) {
+    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) {
+    const set = new Set();
+    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, secret) {
+    const more = secret === undefined ? undefined : headerNames(secret);
     const out = {};
     for (const [key, value] of Object.entries(headers)) {
-        if (!SECRET_HEADERS.has(key.toLowerCase()) && typeof value === "string")
+        if (!isSecretHeader(key, more) && typeof value === "string")
             out[key] = value;
     }
     return out;
@@ -29,4 +50,94 @@ export function credentialsOf(request) {
     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) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.filter((item) => 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) {
+    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) {
+    const text = Array.isArray(header) ? header.filter((item) => typeof item === "string").join("; ") : header;
+    if (typeof text !== "string" || text === "")
+        return {};
+    const cookies = new Map();
+    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) {
+    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) {
+    const values = new Map();
+    for (const [key, value] of query)
+        if (!values.has(key))
+            values.set(key, value);
+    return Object.fromEntries(values);
+}
+/**
+ * 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, options = {}) {
+    const headers = new Map();
+    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),
+    };
+}
 //# sourceMappingURL=request-auth.js.map

package/dist/server/request-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"request-auth.js","sourceRoot":"","sources":["../../src/server/request-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,sFAAsF;AACtF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,qBAAqB,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;AAEhG,sFAAsF;AACtF,MAAM,UAAU,oBAAoB,CAAC,OAAgC;IACnE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC5F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,MAAe;IACtC,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuE;IACnG,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxF,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC"}
+{"version":3,"file":"request-auth.js","sourceRoot":"","sources":["../../src/server/request-auth.ts"],"names":[],"mappings":"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"}

package/dist/server/types.d.ts

@@ -4,7 +4,10 @@
  * Protocol-agnostic server types mirroring the client architecture.
  * 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";
 export type { Method };
 /**
  * Server request in unified RPC format.
@@ -19,23 +22,74 @@ export interface ServerRequest<TReq = unknown> {
     payload: TReq;
     /** 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". */
@@ -53,7 +107,21 @@ 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.

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/server/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwJH;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,MAAc;QACxB,KAAK,CACH,wBAAwB,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,GACxD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAC7C,EAAE,CACH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGlB,IAAI;IACJ,SAAS;IAH3B,YACE,OAAe,EACC,IAAI,GAAW,KAAK,EACpB,SAAS,GAAY,KAAK;QAE1C,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHC,IAAI;yBACJ,SAAS;QAGzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqOH;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,MAAc;QACxB,KAAK,CACH,wBAAwB,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,GACxD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAC7C,EAAE,CACH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGlB,IAAI;IACJ,SAAS;IAH3B,YACE,OAAe,EACC,IAAI,GAAW,KAAK,EACpB,SAAS,GAAY,KAAK;QAE1C,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHC,IAAI;yBACJ,SAAS;QAGzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/client",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Procedures as data for TypeScript: define typed procedures once and call them in process, over HTTP, WebSocket, the CLI or MCP. Streaming, middleware, retries, caching and a JSON program format.",
   "keywords": [
     "rpc",
@@ -70,6 +70,10 @@
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js"
+    },
+    "./query": {
+      "types": "./dist/procedures/collection/query.d.ts",
+      "import": "./dist/procedures/collection/query.js"
     }
   },
   "files": [

package/src/adapters/http/client/transport.ts

@@ -83,6 +83,10 @@ export class HttpTransport implements Transport {
   private readonly headerConverter: HeaderConverter;
   private readonly defaultHeaders: Record<string, string>;
   private readonly timeout: number | undefined;
+  /** The more options of each fetch call: the credentials mode and the others (CLI-18) */
+  private readonly requestInit: Omit<RequestInit, "method" | "headers" | "body" | "signal">;
+  /** The fetch function, or undefined for the global fetch at the time of each call */
+  private readonly fetchFn: typeof fetch | undefined;
 
   constructor(options: HttpTransportOptions) {
     this.baseUrl = options.baseUrl;
@@ -93,6 +97,11 @@ export class HttpTransport implements Transport {
       options.headerConverter || createDefaultHeaderConverter();
     this.defaultHeaders = options.defaultHeaders || {};
     this.timeout = optionalMs(options.timeout, "timeout");
+    this.requestInit = {
+      ...options.requestInit,
+      ...(options.credentials !== undefined ? { credentials: options.credentials } : {}),
+    };
+    this.fetchFn = options.fetch;
   }
 
   /**
@@ -136,6 +145,7 @@ export class HttpTransport implements Transport {
 
       // Build fetch options
       const fetchOptions: RequestInit = {
+        ...this.requestInit,
         method: httpMethod,
         headers: {
           [HTTPHeaders.CONTENT_TYPE]: "application/json",
@@ -156,7 +166,7 @@ export class HttpTransport implements Transport {
       }
 
       // Execute HTTP request
-      const response = await fetch(url, fetchOptions);
+      const response = await (this.fetchFn ?? fetch)(url, fetchOptions);
       const metadata = this.headerConverter.headersToMetadata(response.headers);
 
       if (response.headers.get(HTTPHeaders.CONTENT_TYPE)?.includes(NDJSON) && response.body) {

package/src/adapters/http/client/types.ts

@@ -31,4 +31,26 @@ export interface HttpTransportOptions {
 
   /** The time to the first item of a response, for example `seconds(30)` */
   timeout?: Duration;
+
+  /**
+   * The credentials mode of `fetch` (CLI-18). `"include"` sends the cookies of the server to
+   * another origin too. An application with a cookie session needs it for procedures on another
+   * origin. The server then must permit the origin with credentials (CORS). This option goes over
+   * `requestInit.credentials`.
+   * @default the default of `fetch`: "same-origin"
+   */
+  credentials?: "include" | "same-origin" | "omit";
+
+  /**
+   * More options of each `fetch` call: `mode`, `cache`, `redirect`, `referrerPolicy`, `keepalive`,
+   * `priority` and the others. The transport sets `method`, `headers`, `body` and `signal` itself.
+   */
+  requestInit?: Omit<RequestInit, "method" | "headers" | "body" | "signal">;
+
+  /**
+   * The `fetch` function of the transport, for example a `fetch` with a cookie jar in Node, or a
+   * test double.
+   * @default globalThis.fetch
+   */
+  fetch?: typeof fetch;
 }

package/src/adapters/http/server/cors.ts

@@ -0,0 +1,144 @@
+/**
+ * The CORS headers of a procedure server, without a framework. `procedureHandler` applies them to
+ * the requests on its path. The Express shim `HttpServerTransport` applies them to each request of
+ * its app, as before. This module imports only the types of `node:http`.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { HTTPHeaders, HTTPMethod } from "../shared/index.js";
+import { PROTOCOL_HEADER } from "../../../protocol.js";
+import { toMs, type Duration } from "../../../duration.js";
+
+/** The CORS options of a procedure server. */
+export interface CorsOptions {
+  /**
+   * The origins that can read the responses: `"*"`, one origin, a list, or a function that
+   * decides for each origin. A response names the origin of the request when the origin is
+   * permitted, with `Vary: Origin`.
+   * @default "*"
+   */
+  readonly origin?: string | readonly string[] | ((origin: string) => boolean) | undefined;
+  /** The methods of `Access-Control-Allow-Methods`. @default GET, POST, PUT, DELETE, PATCH, OPTIONS */
+  readonly methods?: readonly string[] | undefined;
+  /** The request headers of `Access-Control-Allow-Headers`. @default the headers of `HttpTransport` */
+  readonly allowedHeaders?: readonly string[] | undefined;
+  /** The response headers that a page can read (`Access-Control-Expose-Headers`). @default none */
+  readonly exposedHeaders?: readonly string[] | undefined;
+  /**
+   * True: a page can send cookies (`fetch` with `credentials: "include"`). The response then has
+   * `Access-Control-Allow-Credentials: true`. A browser refuses `"*"` with credentials, so give the
+   * origins.
+   */
+  readonly credentials?: boolean | undefined;
+  /** The time that a browser keeps the answer to a preflight request (`Access-Control-Max-Age`). */
+  readonly maxAge?: Duration | undefined;
+}
+
+/** The request headers that `HttpTransport` sends: the default `allowedHeaders`. */
+export const DEFAULT_CORS_HEADERS: readonly string[] = Object.freeze([
+  "Content-Type",
+  "Accept",
+  HTTPHeaders.AUTHORIZATION,
+  HTTPHeaders.API_KEY,
+  HTTPHeaders.REQUEST_ID,
+  HTTPHeaders.TRACE_ID,
+  HTTPHeaders.SPAN_ID,
+  HTTPHeaders.PARENT_SPAN_ID,
+  "traceparent",
+  PROTOCOL_HEADER,
+  HTTPHeaders.METADATA,
+  "collection",
+  "collectionName",
+  "database",
+]);
+
+/** The methods of the default `Access-Control-Allow-Methods`. */
+export const DEFAULT_CORS_METHODS: readonly string[] = Object.freeze([
+  HTTPMethod.GET,
+  HTTPMethod.POST,
+  HTTPMethod.PUT,
+  HTTPMethod.DELETE,
+  HTTPMethod.PATCH,
+  HTTPMethod.OPTIONS,
+]);
+
+/** The CORS options with their defaults, ready for each request. */
+export interface CorsPolicy {
+  /** The permitted origin to send back for a request origin, or undefined for none. */
+  readonly allowOrigin: (requestOrigin: string | undefined) => string | undefined;
+  /** True when the permitted origin depends on the request: the response gets `Vary: Origin`. */
+  readonly varies: boolean;
+  readonly methods: string | undefined;
+  readonly allowedHeaders: string | undefined;
+  readonly exposedHeaders: string | undefined;
+  readonly credentials: boolean;
+  /** The value of `Access-Control-Max-Age` in seconds, or undefined. */
+  readonly maxAge: string | undefined;
+}
+
+/**
+ * This function makes the CORS policy of the options. `defaultCredentials` is the default of the
+ * `credentials` option.
+ */
+export function corsPolicy(options: CorsOptions, defaultCredentials: boolean): CorsPolicy {
+  const origin = options.origin ?? "*";
+  const allowOrigin = (requestOrigin: string | undefined): string | undefined => {
+    if (origin === "*") return "*";
+    if (requestOrigin === undefined) return undefined;
+    if (typeof origin === "function") return origin(requestOrigin) ? requestOrigin : undefined;
+    const list: readonly string[] = typeof origin === "string" ? [origin] : origin;
+    return list.includes(requestOrigin) ? requestOrigin : undefined;
+  };
+  const join = (list: readonly string[] | undefined): string | undefined => (list === undefined || list.length === 0 ? undefined : list.join(", "));
+  const maxAgeMs = options.maxAge === undefined ? undefined : toMs(options.maxAge, "cors.maxAge");
+  return {
+    allowOrigin,
+    varies: origin !== "*",
+    methods: join("methods" in options ? options.methods : DEFAULT_CORS_METHODS),
+    allowedHeaders: join("allowedHeaders" in options ? options.allowedHeaders : DEFAULT_CORS_HEADERS),
+    exposedHeaders: join(options.exposedHeaders),
+    credentials: options.credentials ?? defaultCredentials,
+    maxAge: maxAgeMs === undefined || maxAgeMs <= 0 ? undefined : String(Math.floor(maxAgeMs / 1000)),
+  };
+}
+
+/** This function adds a value to the `Vary` header of a response, one time. */
+function vary(res: ServerResponse, field: string): void {
+  const current = res.getHeader("Vary");
+  const text = Array.isArray(current) ? current.join(", ") : current === undefined ? "" : String(current);
+  const fields = text.split(",").map((part) => part.trim().toLowerCase());
+  if (fields.includes("*") || fields.includes(field.toLowerCase())) return;
+  res.setHeader("Vary", text.trim() === "" ? field : `${text}, ${field}`);
+}
+
+/**
+ * This function sets the CORS headers of a response. It gives true for a preflight request
+ * (`OPTIONS`): the function then ends the response with 204.
+ */
+export function applyCors(req: IncomingMessage, res: ServerResponse, policy: CorsPolicy): boolean {
+  const requestOrigin = typeof req.headers.origin === "string" ? req.headers.origin : undefined;
+  const allowed = policy.allowOrigin(requestOrigin);
+  if (policy.varies) vary(res, "Origin");
+  if (allowed !== undefined) res.setHeader("Access-Control-Allow-Origin", allowed);
+  if (policy.methods !== undefined) res.setHeader("Access-Control-Allow-Methods", policy.methods);
+  if (policy.allowedHeaders !== undefined) res.setHeader("Access-Control-Allow-Headers", policy.allowedHeaders);
+  if (policy.exposedHeaders !== undefined) res.setHeader("Access-Control-Expose-Headers", policy.exposedHeaders);
+  if (policy.credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
+  if (req.method !== "OPTIONS") return false;
+  if (policy.maxAge !== undefined) res.setHeader("Access-Control-Max-Age", policy.maxAge);
+  res.statusCode = 204;
+  res.end();
+  return true;
+}
+
+/**
+ * The origins that the CORS options permit, for the browser checks: a page that CORS lets read the
+ * response can also send a call. Without CORS, no other origin can send a call.
+ */
+export function corsOrigins(cors: CorsOptions | undefined): readonly string[] | "*" | ((origin: string) => boolean) {
+  if (!cors) return [];
+  const origin = cors.origin ?? "*";
+  if (origin === "*") return "*";
+  if (typeof origin === "function") return origin;
+  return typeof origin === "string" ? [origin] : origin;
+}