@procedures/client 0.8.0 → 0.9.0

package/src/server/request-auth.ts

@@ -1,19 +1,41 @@
 /**
  * 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.
  */
 
 import type { Credentials } from "./types.js";
 
 /** 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"]);
+const SECRET_HEADERS: ReadonlySet<string> = 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: Record<string, unknown>): Record<string, string> {
+/**
+ * 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: string, more?: ReadonlySet<string>): boolean {
+  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: Iterable<string> | undefined): ReadonlySet<string> {
+  const set = new Set<string>();
+  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: Record<string, unknown>, secret?: Iterable<string>): Record<string, string> {
+  const more = secret === undefined ? undefined : headerNames(secret);
   const out: Record<string, string> = {};
   for (const [key, value] of Object.entries(headers)) {
-    if (!SECRET_HEADERS.has(key.toLowerCase()) && typeof value === "string") out[key] = value;
+    if (!isSecretHeader(key, more) && typeof value === "string") out[key] = value;
   }
   return out;
 }
@@ -33,3 +55,103 @@ export function credentialsOf(request: { headers: Record<string, unknown>; url?:
   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: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.filter((item): item is string => 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: string): string {
+  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: unknown): Record<string, string> {
+  const text = Array.isArray(header) ? header.filter((item): item is string => typeof item === "string").join("; ") : header;
+  if (typeof text !== "string" || text === "") return {};
+  const cookies = new Map<string, string>();
+  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: string | undefined): { path: string; query: URLSearchParams } {
+  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: URLSearchParams): Record<string, string> {
+  const values = new Map<string, string>();
+  for (const [key, value] of query) if (!values.has(key)) values.set(key, value);
+  return Object.fromEntries(values);
+}
+
+/** The options of `requestCredentials`. */
+export interface RequestCredentialsOptions {
+  /**
+   * The query parameter whose value is the bearer token of a request without an
+   * `Authorization: Bearer` header. A browser WebSocket cannot set headers, so the WebSocket
+   * server reads `token`. `false` reads no query parameter.
+   * @default false
+   */
+  readonly tokenQuery?: string | false | undefined;
+}
+
+/**
+ * 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: { headers: Record<string, unknown>; url?: string | undefined },
+  options: RequestCredentialsOptions = {}
+): Credentials {
+  const headers = new Map<string, string>();
+  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),
+  };
+}

package/src/server/types.ts

@@ -5,7 +5,10 @@
  * 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";
 
 // Re-export Method from client types
 export type { Method };
@@ -27,27 +30,86 @@ export interface ServerRequest<TReq = unknown> {
   /** 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". */
@@ -66,8 +128,23 @@ 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.