@procedures/client 0.7.0 → 0.8.1

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":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,YAAY,EAAE,MAAM,EAAE,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,OAAO;IAC3C,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IAEX,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IAEf,sBAAsB;IACtB,OAAO,EAAE,IAAI,CAAC;IAEd,qDAAqD;IACrD,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAEtC,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAEtC,+GAA+G;IAC/G,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAElC;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChE,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChE,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,KAC5B,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;AAExE,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,IAAI,GAAG,OAAO;IAC5C,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,iDAAiD;IACjD,OAAO,CAAC,EAAE,IAAI,CAAC;IAEf;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAE7B,wBAAwB;IACxB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,IAAI,CAC1D,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,KACzB,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,OAAO;IAC3C,2BAA2B;IAC3B,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAE7B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,IAAI,CACzD,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,KACzB,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,IAAI,CAC7D,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,KAC3B,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,MAAM,EAAE,MAAM,EAOzB;CACF;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,OAAO;IAHpC,YACE,OAAO,EAAE,MAAM,EACC,IAAI,GAAE,MAAc,EACpB,SAAS,GAAE,OAAe,EAI3C;CACF"}

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/dist/timers.d.ts

@@ -57,6 +57,11 @@ export interface TimerDefaults {
     readonly server: {
         /** The time that `ProcedureServer.stop()` waits for the calls that run. */
         readonly stopGraceMs: number;
+        /**
+         * The longest time that `ProcedureServer.useStorage` with `close` waits for the calls on the
+         * old storage, before it closes the old storage.
+         */
+        readonly storageGraceMs: number;
     };
 }
 /** The default times of the core. The middleware, the transports and the server read them. */

package/dist/timers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,qCAAqC;QACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACnC,+CAA+C;QAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE;QACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KAClC,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE;QACxB,iCAAiC;QACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,gDAAgD;QAChD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,wFAAwF;QACxF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;QACzC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE;QACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,0EAA0E;QAC1E,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;KAC1C,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE;QACnB,yFAAyF;QACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QACpB,kEAAkE;QAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,2EAA2E;QAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED,8FAA8F;AAC9F,eAAO,MAAM,cAAc,EAAE,aAwB3B,CAAC"}
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,qCAAqC;QACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACnC,+CAA+C;QAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE;QACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KAClC,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE;QACxB,iCAAiC;QACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,gDAAgD;QAChD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,wFAAwF;QACxF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;QACzC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE;QACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,0EAA0E;QAC1E,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;KAC1C,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE;QACnB,yFAAyF;QACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QACpB,kEAAkE;QAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,2EAA2E;QAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B;;;WAGG;QACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AAED,8FAA8F;AAC9F,eAAO,MAAM,cAAc,EAAE,aA0B3B,CAAC"}

package/dist/timers.js

@@ -31,6 +31,8 @@ export const TIMER_DEFAULTS = Object.freeze({
     // stream then stays open (WIRE-PROTOCOL.md, "The keep-alive of an NDJSON stream").
     httpServer: Object.freeze({ keepAliveMs: 15_000 }),
     idempotency: Object.freeze({ ttlMs: 10 * 60_000 }),
-    server: Object.freeze({ stopGraceMs: 0 }),
+    // 30 s: the request time of the WebSocket client. A call that runs longer timed out at its
+    // client already.
+    server: Object.freeze({ stopGraceMs: 0, storageGraceMs: 30_000 }),
 });
 //# sourceMappingURL=timers.js.map

package/dist/timers.js.map

@@ -1 +1 @@
-{"version":3,"file":"timers.js","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuDH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,MAAM,CAAC;IACzD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACvH,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IAClF,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;IAChE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;QAC7B,mBAAmB,EAAE,MAAM;QAC3B,gBAAgB,EAAE,MAAM;QACxB,8FAA8F;QAC9F,4FAA4F;QAC5F,mBAAmB,EAAE,MAAM;QAC3B,kBAAkB,EAAE,KAAK;QACzB,eAAe,EAAE,CAAC;QAClB,uBAAuB,EAAE,KAAK;QAC9B,mBAAmB,EAAE,MAAM;KAC5B,CAAC;IACF,+FAA+F;IAC/F,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IACpH,iGAAiG;IACjG,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;CAC1C,CAAC,CAAC"}
+{"version":3,"file":"timers.js","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4DH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,MAAM,CAAC;IACzD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACvH,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IAClF,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;IAChE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;QAC7B,mBAAmB,EAAE,MAAM;QAC3B,gBAAgB,EAAE,MAAM;QACxB,8FAA8F;QAC9F,4FAA4F;QAC5F,mBAAmB,EAAE,MAAM;QAC3B,kBAAkB,EAAE,KAAK;QACzB,eAAe,EAAE,CAAC;QAClB,uBAAuB,EAAE,KAAK;QAC9B,mBAAmB,EAAE,MAAM;KAC5B,CAAC;IACF,+FAA+F;IAC/F,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IACpH,iGAAiG;IACjG,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC;IAClD,2FAA2F;IAC3F,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;CAClE,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/client",
-  "version": "0.7.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;
+}