@procedures/client 0.27.2 → 0.27.4

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

@@ -396,8 +396,9 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
       method,
       payload,
       metadata,
-      // A network request: ProcedureServer examines the token and the request hook (R18, CLI-2a)
-      credentials: requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url }),
+      // A network request: ProcedureServer examines the token and the request hook (R18, CLI-2a).
+      // The credentials have the connection of the socket of the request (CLI-71)
+      credentials: requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url, socket: req.socket }),
     };
   };
 

package/src/adapters/websocket/server/transport.ts

@@ -387,8 +387,9 @@ export class WebSocketServerTransport implements ServerTransport {
     };
     this.trackedConnections.set(connectionId, trackedConnection);
     // The credentials of the upgrade, for each call of the connection: the bearer token of its
-    // Authorization header or of its token query, its cookies, its headers and its query (CLI-2a)
-    const credentials = requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url }, { tokenQuery: "token" });
+    // Authorization header or of its token query, its cookies, its headers and its query (CLI-2a),
+    // and the connection of its socket (CLI-71)
+    const credentials = requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url, socket: req.socket }, { tokenQuery: "token" });
 
     // The calls of this connection in the two directions (roadmap R24)
     const isOpen = (): boolean => ws.readyState === WebSocket.OPEN;

package/src/browser.ts

@@ -99,6 +99,7 @@ export type {
   ServerResponse,
   RequestHandler,
   Credentials,
+  RequestConnection,
   Principal,
   PrincipalOf,
   RequestIdentity,

package/src/server/index.ts

@@ -51,6 +51,7 @@ export {
   type ServerResponse,
   type RequestHandler,
   type Credentials,
+  type RequestConnection,
   type Principal,
   type PrincipalOf,
   type RequestIdentity,

package/src/server/procedure-server.ts

@@ -162,12 +162,12 @@ export interface ProcedureServerOptions extends ServerOptions {
 
   /**
    * 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 local
-   * request (`LOCAL_CREDENTIALS`) does not go through the hook. A server with a hook refuses a
-   * request without credentials, and the hook does not run for it (CLI-1).
+   * header, the query, the connection of the socket) 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 local request (`LOCAL_CREDENTIALS`) does not go through the hook. A server
+   * with a hook refuses a request without credentials, and the hook does not run for it (CLI-1).
    *
    * The hook can run more than one time for one request or one task: `admits()` and `identify()`
    * run it too (CLI-69).

package/src/server/request-auth.ts

@@ -6,7 +6,7 @@
  * This module imports no Node code: a server in a browser or a worker can use it too.
  */
 
-import { LOCAL_MARKER, type Credentials } from "./types.js";
+import { LOCAL_MARKER, type Credentials, type RequestConnection } from "./types.js";
 
 /**
  * The credentials of a local face (CLI-1): a call from this application, not from the network.
@@ -166,13 +166,36 @@ export interface RequestCredentialsOptions {
   readonly tokenQuery?: string | false | undefined;
 }
 
+/** True for a port number of a socket: an integer from 0 to 65535. */
+function isPort(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+
+/**
+ * The connection of a network request (CLI-71): a frozen copy of the addresses and the ports of
+ * its socket. The copy has only the fields that the socket has. A Unix socket or a named pipe
+ * has no ports. No header goes into the copy.
+ */
+function connectionOf(socket: RequestConnection): RequestConnection {
+  const connection: { remoteAddress?: string; remotePort?: number; localAddress?: string; localPort?: number } = {};
+  const { remoteAddress, remotePort, localAddress, localPort } = socket;
+  if (typeof remoteAddress === "string" && remoteAddress !== "") connection.remoteAddress = remoteAddress;
+  if (isPort(remotePort)) connection.remotePort = remotePort;
+  if (typeof localAddress === "string" && localAddress !== "") connection.localAddress = localAddress;
+  if (isPort(localPort)) connection.localPort = localPort;
+  return Object.freeze(connection);
+}
+
 /**
  * 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.
+ *
+ * With `request.socket` (the socket of a request of `node:http`), the credentials also have the
+ * connection of the request (CLI-71): the addresses and the ports of that socket, as frozen data.
  */
 export function requestCredentials(
-  request: { headers: Record<string, unknown>; url?: string | undefined },
+  request: { headers: Record<string, unknown>; url?: string | undefined; socket?: RequestConnection | undefined },
   options: RequestCredentialsOptions = {}
 ): Credentials {
   const headers = new Map<string, string>();
@@ -189,5 +212,6 @@ export function requestCredentials(
     cookies: cookiesOf(headers.get("cookie")),
     headers: Object.fromEntries(headers),
     query: queryRecord(query),
+    ...(request.socket ? { connection: connectionOf(request.socket) } : {}),
   };
 }

package/src/server/types.ts

@@ -97,6 +97,42 @@ export interface Credentials {
   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;
+  /**
+   * The connection of a network request (CLI-71): the addresses and the ports of its socket. A
+   * request hook can find the caller from its TCP peer with it, for example from the process that
+   * owns the remote port. Each network face sets it: the HTTP face, the WebSocket face (the upgrade
+   * and each call) and the Streamable HTTP endpoint of the MCP face.
+   *
+   * - A local request (a call in this process, MCP over stdio, a message port) has no connection.
+   * - An SDK transport of the application (`sdkTransport`, for example the legacy SSE transport of
+   *   the MCP SDK) gives no connection. The SDK gives only the headers and the URL of each request.
+   * - The data comes only from the socket. It does not come from a header, for example
+   *   `X-Forwarded-For` or `Forwarded`. Behind a proxy, the peer is the proxy. Thus a request
+   *   hook that trusts the connection there sees the proxy, not the client.
+   * - The key of the idempotency cache has the principal (audit s21). When the principal comes
+   *   from the connection, two callers behind one address can have one principal. Then a call
+   *   of one caller can get the cached result of a call of the other caller with the same
+   *   idempotency key.
+   */
+  readonly connection?: RequestConnection | undefined;
+}
+
+/**
+ * The connection of a network request (CLI-71): the addresses and the ports of its socket, as
+ * frozen plain data. The face copies them from the socket when the request comes in.
+ *
+ * Each field is optional, because a socket does not always have it. A Unix socket and a named
+ * pipe have no IP addresses and no ports. A socket that closed before the copy has no addresses.
+ */
+export interface RequestConnection {
+  /** The IP address of the other end of the socket: the client, or a proxy. */
+  readonly remoteAddress?: string | undefined;
+  /** The port of the other end of the socket. It is the local port of the socket of the client. */
+  readonly remotePort?: number | undefined;
+  /** The IP address of this end of the socket: the address on which the listener took the request. */
+  readonly localAddress?: string | undefined;
+  /** The port of this end of the socket: the port of the listener. */
+  readonly localPort?: number | undefined;
 }
 
 /**
@@ -120,8 +156,9 @@ export interface RequestIdentity {
 
 /**
  * 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`.
+ * the query, the connection of the socket) 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`.
  *
  * The hook can run more than one time for one request or one task. `admits()` runs it at a
  * WebSocket upgrade, and then each call over the connection runs it again. Thus a hook with a
@@ -133,7 +170,8 @@ export interface RequestIdentity {
  * 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.
+ * metadata or the transport of the request. It reads only the credentials. The credentials of a
+ * network request also have the connection of its socket (`credentials.connection`, CLI-71).
  */
 export type PrincipalOf = (
   credentials: Credentials,