@procedures/client 0.18.1 → 0.20.0

package/src/server/browser-guard.ts

@@ -22,8 +22,6 @@
  * Each refusal is the error `FORBIDDEN` of wire v1, with the status 403 and a reason (CLI-4).
  */
 
-import type { IncomingHttpHeaders } from "node:http";
-
 const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 
 /** The options of the browser checks of a server transport. */
@@ -48,10 +46,24 @@ export interface BrowserGuardOptions {
   allowGet?: boolean | undefined;
 }
 
-/** The parts of an incoming request that the checks read. */
+/**
+ * The headers of a request, by lower-case name. The type is structural, so the root names no Node
+ * module (CLI-61). `IncomingHttpHeaders` of `node:http` agrees with it.
+ */
+export interface GuardedHeaders {
+  readonly [name: string]: string | string[] | undefined;
+  readonly host?: string | undefined;
+  readonly origin?: string | undefined;
+  readonly cookie?: string | undefined;
+  readonly "content-type"?: string | undefined;
+  readonly "content-length"?: string | undefined;
+  readonly "transfer-encoding"?: string | undefined;
+}
+
+/** The parts of an incoming request that the checks read. An `IncomingMessage` of `node:http` agrees with it. */
 export interface GuardedRequest {
   method?: string | undefined;
-  headers: IncomingHttpHeaders;
+  headers: GuardedHeaders;
   socket?: { localAddress?: string | undefined } | undefined;
 }
 
@@ -121,7 +133,7 @@ function isJsonType(contentType: string | undefined): boolean {
 }
 
 /** True when the request has a body: a `Content-Length` above 0, or a chunked body. */
-function hasBody(headers: IncomingHttpHeaders): boolean {
+function hasBody(headers: GuardedHeaders): boolean {
   const length = Number(headers["content-length"] ?? 0);
   return length > 0 || headers["transfer-encoding"] !== undefined;
 }
@@ -130,7 +142,7 @@ function hasBody(headers: IncomingHttpHeaders): boolean {
  * 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 {
+export function hasAmbientCredentials(headers: GuardedHeaders): boolean {
   const cookie = headers.cookie;
   return typeof cookie === "string" && cookie.trim() !== "";
 }
@@ -143,7 +155,7 @@ export function hasAmbientCredentials(headers: IncomingHttpHeaders): boolean {
  *
  * @internal
  */
-export function needsNamedOrigin(mode: "always" | "cookies" | undefined, headers: IncomingHttpHeaders, cookiesNamed: boolean): boolean {
+export function needsNamedOrigin(mode: "always" | "cookies" | undefined, headers: GuardedHeaders, cookiesNamed: boolean): boolean {
   return mode === "always" || (hasAmbientCredentials(headers) && (cookiesNamed || mode !== undefined));
 }
 

package/src/server/index.ts

@@ -11,8 +11,8 @@
  * - Handler registry with pattern matching
  * - Graceful shutdown
  *
- * The server transports have the entry `@procedures/client/node` (CLI-6). This entry still
- * exports them as deprecated aliases. The next MINOR removes the aliases.
+ * The server transports have the entry `@procedures/client/node` (CLI-6). This entry imports no
+ * Node built-in, no `ws` and no `express`, and its declarations name none of them (CLI-61).
  *
  * @example
  * ```typescript
@@ -38,19 +38,6 @@
  * ```
  */
 
-import { HttpServerTransport as NodeHttpServerTransport } from "../adapters/http/server/transport.js";
-import type {
-  HttpServerTransportOptions as NodeHttpServerTransportOptions,
-  HttpUrlStrategy as NodeHttpUrlStrategy,
-} from "../adapters/http/server/types.js";
-import { WebSocketServerTransport as NodeWebSocketServerTransport } from "../adapters/websocket/server/transport.js";
-import type {
-  WebSocketServerTransportOptions as NodeWebSocketServerTransportOptions,
-  WebSocketAuthHandler as NodeWebSocketAuthHandler,
-  WebSocketConnectionHandler as NodeWebSocketConnectionHandler,
-  WebSocketMessage as NodeWebSocketMessage,
-} from "../adapters/websocket/server/types.js";
-
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
 
@@ -77,78 +64,4 @@ export {
 } from "./types.js";
 
 export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "../adapters/http/server/strategies.js";
-
-// ============================================================================
-// The server transports: deprecated here (CLI-6 step 1)
-// ============================================================================
-// Their entry is `@procedures/client/node`. This entry and the root (which re-exports these
-// names from this module) give them through deprecated aliases until the next MINOR, so an
-// editor marks each old import. Each alias is the same class or type as the export of ./node.
-
-/**
- * The HTTP server transport of Express, a shim over `procedureHandler`.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export const HttpServerTransport: typeof NodeHttpServerTransport = NodeHttpServerTransport;
-/**
- * The HTTP server transport of Express, a shim over `procedureHandler`.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type HttpServerTransport = NodeHttpServerTransport;
-
-/**
- * The options of `HttpServerTransport`.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type HttpServerTransportOptions = NodeHttpServerTransportOptions;
-
-/**
- * The URL strategy of `HttpServerTransport`: it gives the method of an Express request.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type HttpUrlStrategy = NodeHttpUrlStrategy;
-
-/**
- * The WebSocket server transport, on the `ws` package.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export const WebSocketServerTransport: typeof NodeWebSocketServerTransport = NodeWebSocketServerTransport;
-/**
- * The WebSocket server transport, on the `ws` package.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type WebSocketServerTransport = NodeWebSocketServerTransport;
-
-/**
- * The options of `WebSocketServerTransport`.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type WebSocketServerTransportOptions = NodeWebSocketServerTransportOptions;
-
-/**
- * The authentication handler of `WebSocketServerTransport`, for each upgrade request.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type WebSocketAuthHandler = NodeWebSocketAuthHandler;
-
-/**
- * The connection handler of `WebSocketServerTransport`, for each new connection.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type WebSocketConnectionHandler = NodeWebSocketConnectionHandler;
-
-/**
- * The RPC message of `WebSocketServerTransport`.
- *
- * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
- */
-export type WebSocketMessage<TReq = unknown> = NodeWebSocketMessage<TReq>;
+export type { RoutedRequest } from "../adapters/http/server/strategies.js";

package/src/server/procedure-server.ts

@@ -8,6 +8,7 @@
 import { Server, type ServerOptions } from "./server.js";
 import type { 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 {
   AnyProcedure,
   ProcedurePath,
@@ -135,10 +136,11 @@ export interface ProcedureServerOptions extends ServerOptions {
   idempotency?: IdempotencyOptions | false | undefined;
 
   /**
-   * The token of the server (roadmap R18). Each request with credentials (a network request)
-   * must present it as its bearer token, or the server answers `UNAUTHORIZED`. Before, only the
-   * Express middleware of the peer examined the token, so a `ProcedureServer` with the HTTP or
-   * WebSocket transport of the core and the token of a host policy accepted each request.
+   * The token of the server (roadmap R18). Each request must present it as its bearer token, or
+   * the server answers `UNAUTHORIZED`. Only a local request (`LOCAL_CREDENTIALS`) skips it. The
+   * server refuses a request without credentials (CLI-1). Before, only the Express middleware of
+   * the peer examined the token, so a `ProcedureServer` with the HTTP or WebSocket transport of the
+   * core and the token of a host policy accepted each request.
    */
   token?: string | undefined;
 
@@ -154,8 +156,9 @@ export interface ProcedureServerOptions extends ServerOptions {
    * 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.
+   * `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).
    */
   principalOf?: PrincipalOf | undefined;
 
@@ -888,7 +891,9 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   /**
    * 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
+   * 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.
    */
@@ -898,7 +903,15 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       status: { type: "error", code: "UNAUTHORIZED", message, retryable: false },
       metadata: {},
     });
-    const credentials = request.credentials;
+    // 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.
+    if (request.credentials === undefined && (this.token !== undefined || this.principalOf !== undefined)) {
+      return unauthorized("Unauthorized: this server authenticates each request, and the request has no credentials");
+    }
+    // A local face (this process, MCP over stdio, a message port) sets the local marker. The
+    // marker key is a symbol, so a request from the network cannot carry it (CLI-1).
+    const credentials = isLocalCredentials(request.credentials) ? undefined : request.credentials;
     let identity: RequestIdentity | undefined;
     if (this.principalOf && credentials !== undefined) {
       try {
@@ -975,7 +988,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * This method tells if the server admits a connection with these credentials, before its first
    * call. It uses the path of each call: the request hook, the token check and the authenticate
    * function (R18, CLI-2a). A face of connections refuses the upgrade when it gives false (CLI-7).
-   * A request hook that accepts a request without credentials (an empty identity) admits it.
+   * A request hook that accepts empty credentials (`{}`) with an empty identity admits the
+   * connection.
    */
   async admits(credentials: Credentials): Promise<boolean> {
     const request: ServerRequest<unknown> = { id: "connection", method: { service: "", operation: "" }, payload: undefined, metadata: {}, credentials };

package/src/server/request-auth.ts

@@ -6,7 +6,26 @@
  * This module imports no Node code: a server in a browser or a worker can use it too.
  */
 
-import type { Credentials } from "./types.js";
+import { LOCAL_MARKER, type Credentials } from "./types.js";
+
+/**
+ * The credentials of a local face (CLI-1): a call from this application, not from the network.
+ * The server applies no token and no request hook to a request with them.
+ *
+ * Only these faces set them:
+ * - A call in this process: a direct `handle()` of the code of the application.
+ * - MCP over stdio: the peer is the parent process that started this process.
+ * - A message port (`PortTransport`): only the holder of the other end of the port can send.
+ *
+ * A network face (HTTP, WebSocket, MCP over Streamable HTTP) never sets them. The marker key is a
+ * symbol, so no request from the network can carry it.
+ */
+export const LOCAL_CREDENTIALS: Credentials = Object.freeze({ [LOCAL_MARKER]: true as const });
+
+/** True when the credentials carry the local marker (CLI-1): the request comes from this application. */
+export function isLocalCredentials(credentials: Credentials | undefined): boolean {
+  return credentials?.[LOCAL_MARKER] === true;
+}
 
 /** The headers that carry a secret. They do not go into the metadata of a request. */
 const SECRET_HEADERS: ReadonlySet<string> = new Set(["authorization", "proxy-authorization", "cookie", "x-api-key"]);

package/src/server/types.ts

@@ -48,11 +48,14 @@ export interface ServerRequest<TReq = unknown> {
   signal?: AbortSignal;
 
   /**
-   * 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).
+   * The credentials of the request (roadmap R18). A network face reads them from the request: the
+   * bearer token of an `Authorization` header or of the `token` query of a WebSocket connection,
+   * the cookies, the headers and the query. A local face sets `LOCAL_CREDENTIALS` (CLI-1). They are
+   * not in the metadata, so a handler and a nested call do not see them.
+   *
+   * A server with a token or a request hook (`principalOf`) refuses a request without credentials
+   * with `UNAUTHORIZED`, and the hook does not run (CLI-1). Before, such a request skipped the
+   * token check and the hook.
    */
   credentials?: Credentials | undefined;
 
@@ -67,11 +70,25 @@ export interface ServerRequest<TReq = unknown> {
   narrowing?: CapabilityRequest | undefined;
 }
 
+/**
+ * The key of the local marker of credentials (CLI-1). The key is a symbol. JSON, structured clone,
+ * a header, a cookie and a query cannot carry a symbol key. Thus a remote request cannot claim to
+ * be local. Use `LOCAL_CREDENTIALS` to set the marker.
+ */
+export const LOCAL_MARKER: unique symbol = Symbol.for("@procedures/client.local-credentials");
+
 /**
  * The credentials of a request. A network transport sets each field that it can read. The request
- * hook of the server (`principalOf`) reads them.
+ * hook of the server (`principalOf`) reads them. A local face sets only the local marker
+ * (`LOCAL_CREDENTIALS`).
  */
 export interface Credentials {
+  /**
+   * The local marker (CLI-1): the request comes from this application, not from the network. The
+   * server applies no token and no request hook to a local request. Only a local face sets it: a
+   * call in this process, MCP over stdio, or a message port. A network face never sets it.
+   */
+  readonly [LOCAL_MARKER]?: true | undefined;
   /** 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). */