@procedures/client 0.26.2 → 0.27.0

package/src/server/procedure-server.ts

@@ -6,7 +6,7 @@
  */
 
 import { Server, type ServerOptions } from "./server.js";
-import type { AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
+import type { Admission, AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
 import type {
@@ -149,6 +149,13 @@ export interface ProcedureServerOptions extends ServerOptions {
    * `UNAUTHORIZED`. It runs after the token check. The capability function can read
    * `request.principal`. Like the request hook, it can run more than one time for one request or
    * one task: `admits()` and `identify()` run it too (roadmap CLI-69).
+   *
+   * On the MCP HTTP face, it runs one time for each HTTP request, in `admission()` (CLI-2b). The
+   * tool calls of the request use that admission, so the function does not run for each call. For
+   * `admission()`, `admits()` and `identify()`, the request has an empty method
+   * (`{ service: "", operation: "" }`), the id `admission`, `connection` or `identify`, no payload
+   * and no metadata. Thus the function must not branch on the method, the payload, the metadata
+   * or the transport of the request. It reads only the credentials and the principal.
    */
   authenticate?: ((request: ServerRequest<unknown>) => Principal | undefined | Promise<Principal | undefined>) | undefined;
 
@@ -319,7 +326,7 @@ async function* forgottenAtRetryableEnd<T>(items: AsyncIterable<T>, forget: () =
   }
 }
 
-/** The request of credentials without a call: `admits()` and `identify()` give it to the checks of each call. */
+/** The request of credentials without a call: `admits()`, `identify()` and `admission()` give it to the checks of each call. */
 function credentialsRequest(id: string, credentials: Credentials): ServerRequest<unknown> {
   return { id, method: { service: "", operation: "" }, payload: undefined, metadata: {}, credentials };
 }
@@ -478,6 +485,11 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   private readonly token: string | undefined;
   private readonly principalOf: PrincipalOf | undefined;
   private readonly authenticate: ProcedureServerOptions["authenticate"];
+  /**
+   * The admissions of this server (CLI-2b): the identity of each object of admitted credentials
+   * that `admission()` gave. Only this server adds an entry, so a request cannot claim one.
+   */
+  private readonly admissions = new WeakMap<Credentials, { readonly principal: Principal | undefined; readonly narrowing: ServerRequest<unknown>["narrowing"] }>();
   /** The functions that `drain()` 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. */
@@ -921,8 +933,9 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * network request must present the token. Only a local request (`LOCAL_CREDENTIALS`) skips the
    * hook and the token. A request without credentials is not local: a server with a token or a
    * request hook refuses it, and the hook does not run (CLI-1). The authenticate function gives
-   * the principal. The function gives an UNAUTHORIZED response, or undefined when the request
-   * passes.
+   * the principal. The credentials of an admission of this server (`admission()`) skip the
+   * checks: the request gets the principal and the narrowing of that admission (CLI-2b). 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> => ({
@@ -930,6 +943,17 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       status: { type: "error", code: "UNAUTHORIZED", message, retryable: false },
       metadata: {},
     });
+    // A face admitted the network request of this call one time (CLI-2b): the checks do not run
+    // again. Only this server makes such credentials, so a copy or a forgery has no entry.
+    const admitted = request.credentials !== undefined ? this.admissions.get(request.credentials) : undefined;
+    if (admitted) {
+      if (admitted.principal) request.principal = admitted.principal;
+      if (admitted.narrowing) {
+        const order = this.capabilityOptions.clearanceOrder;
+        request.narrowing = request.narrowing ? joinNarrowing(request.narrowing, admitted.narrowing, order) : admitted.narrowing;
+      }
+      return undefined;
+    }
     // Only a local request skips the token and the request hook (CLI-1). A face that sets no
     // credentials skips neither: the server refuses it, and the hook does not run. Before, such a
     // request passed as a request of this process.
@@ -1034,6 +1058,25 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     return (await this.admit(request)) === undefined ? request.principal : undefined;
   }
 
+  /**
+   * This method admits a network request one time, before its calls (CLI-2b). It runs the checks
+   * of each call: the request hook, the token check and the authenticate function. The admitted
+   * credentials are a new object. A call with them gets the principal and the narrowing of the
+   * admission, and the checks do not run again for it. Only the admitted object skips the checks:
+   * a copy of it and the credentials of another server go through them. A face gives the
+   * admitted credentials only to the calls of the same network request.
+   */
+  async admission(credentials: Credentials): Promise<Admission> {
+    const request = credentialsRequest("admission", credentials);
+    const refusal = await this.admit(request);
+    if (refusal) {
+      return { ok: false, code: "UNAUTHORIZED", message: refusal.status.type === "error" ? refusal.status.message : "Unauthorized" };
+    }
+    const admitted: Credentials = Object.freeze({ ...credentials });
+    this.admissions.set(admitted, { principal: request.principal, narrowing: request.narrowing });
+    return { ok: true, credentials: admitted, ...(request.principal ? { principal: request.principal } : {}) };
+  }
+
   /**
    * Run a keyed call one time. The run continues when its caller goes away, so that the next try
    * gets its result: only the deadline of the call and the stop of the server end it. A stream

package/src/server/types.ts

@@ -124,8 +124,16 @@ export interface RequestIdentity {
  * with `UNAUTHORIZED`. The hook runs before the token check and before `authenticate`.
  *
  * The hook can run more than one time for one request or one task. `admits()` runs it at a
- * WebSocket upgrade, and `identify()` runs it before the MCP face makes a task (roadmap CLI-69).
- * Thus a hook with a side effect, for example a count or a log line, sees each of these runs.
+ * WebSocket upgrade, and then each call over the connection runs it again. Thus a hook with a
+ * side effect, for example a count or a log line, sees each of these runs.
+ *
+ * On the MCP HTTP face, the hook runs one time for each HTTP request, before its calls (CLI-2b):
+ * `admission()` runs it for `initialize`, a tool call, the GET stream and the DELETE of a session.
+ * A tool call, and `identify()` before a task (CLI-69), use that admission: the hook does not run
+ * again for them. For `admission()`, `admits()` and `identify()`, the request of the hook has an
+ * empty method (`{ service: "", operation: "" }`), the id `admission`, `connection` or `identify`,
+ * no payload and no metadata. Thus a hook must not branch on the method, the payload, the
+ * metadata or the transport of the request. It reads only the credentials.
  */
 export type PrincipalOf = (
   credentials: Credentials,
@@ -180,8 +188,26 @@ export interface RequestHandler {
    * only in the call.
    */
   identify?(credentials: Credentials): Promise<Principal | undefined>;
+  /**
+   * This function admits a network request one time, before its calls (CLI-2b). It uses the
+   * checks of each call: the request hook, the token check and the authenticate function. A face
+   * that carries the calls of one network request (MCP over Streamable HTTP) gives the admitted
+   * credentials to those calls, so the checks run one time for the request. `ProcedureServer` has
+   * it. Absent: the handler examines each call, and the face refuses no request before its calls.
+   */
+  admission?(credentials: Credentials): Promise<Admission>;
 }
 
+/**
+ * The result of `admission()` of a request handler (CLI-2b). A request that passes gets its
+ * admitted credentials and its principal. Each call of that request with the admitted credentials
+ * gets the principal and the narrowing of the admission, and the checks do not run again. A
+ * refused request gets `UNAUTHORIZED` and the message of the refusal.
+ */
+export type Admission =
+  | { readonly ok: true; readonly credentials: Credentials; readonly principal?: Principal | undefined }
+  | { readonly ok: false; readonly code: "UNAUTHORIZED"; readonly message: string };
+
 /**
  * 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