@procedures/client 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @procedures/client
 
+## 0.19.0
+
+### Minor Changes
+
+- 5cb934d: Breaking: a `ProcedureServer` with a token or a request hook (`principalOf`) refuses a request without credentials (CLI-1). The error code is `UNAUTHORIZED`, and the hook does not run for it. Before, such a request skipped the token check and the request hook. Thus a face that set no credentials, for example a custom transport, went around the authentication.
+  
+  New: the local marker `LOCAL_CREDENTIALS`, with `isLocalCredentials()` and its key `LOCAL_MARKER`. A local face sets it. Only a local request skips the token and the request hook.
+  
+  The server examines a request in one of three ways:
+  
+  - A local request skips the token and the request hook.
+  - A request without credentials gets `UNAUTHORIZED` when the server has a token or a request hook.
+  - A request with credentials goes through the request hook and the token check, as before.
+  
+  - The local faces are MCP over stdio, an SDK transport of `McpServerTransport` and `PortTransport`. The peer of stdio is the parent process. Only the holder of the other end of a port can send to it.
+  - A network face never sets the marker: HTTP, WebSocket and MCP over Streamable HTTP. The key of the marker is a symbol. JSON, structured clone, a header, a cookie and a query cannot carry it.
+  - The calls of a WebSocket server to the `serve` handler of its client are not local. Their credentials are empty, so a `serve` server with a token refuses them.
+  - `PortTransport` has the new option `credentials`. Give `{}` for a port that a part outside the application can reach, for example a `Window`.
+  - The nested calls of a procedure do not go through the token check. They keep the principal of their caller.
+  
+  Migration:
+  
+  - A custom transport or face that sends no credentials to a server with a token or a request hook now gets `UNAUTHORIZED`. Set the credentials of its request (`requestCredentials()`), or `LOCAL_CREDENTIALS` for a face in this process.
+  - Code that calls `server.handle()` of a server with a token or a request hook gives `credentials: LOCAL_CREDENTIALS`.
+  - The site: no change. Its servers have no token and no request hook, and its workers serve over `PortTransport`, which sets the marker.
+  - MiniMongo: no change. `scripts/dev.ts` starts a server without a token and without a request hook. Its HTTP and WebSocket faces set the credentials of each request.
+  - Graph: no change. The procedure host (`packages/server/graph-host.ts`) has a request hook (`graphPrincipalOf` of `packages/server/graph-procedures.ts`) and no token. All its faces send credentials: HTTP, WebSocket and MCP over Streamable HTTP (`mcpFace`). No code of Graph calls `handle()` directly. The MCP host (`packages/mcp/src/host.ts`) operates over stdio, which is local.
+  - jarvis: no change. The loopback server and the remote server of `packages/http/src/procedures.ts` have a request hook (`principalOf`), and the remote server has a token. `makeProcedureHandler` mounts `procedureHandler`, which sends the credentials of each request. A test that calls `handle()` of such a server gives `LOCAL_CREDENTIALS`, or credentials with the token.
+
+## 0.18.1
+
+### Patch Changes
+
+- d69c8cb: A host that serves a plain collection `a.b` and a collection `a` with partitions fails at registration. To correct it, rename the plain collection. Before, the two had the same topic `collections.a.b`. Thus the readers of `a.b` got the events of the tenant `b` of `a`, a leak across tenants (roadmap CLI-57, decision D23).
+  
+  - The refusal is the new export `CollectionTopicCollisionError`. It names the two collections, the partition and the topic.
+  - `useStorage`, `useStorages`, the option `collections` of a host and `usePartitions` do the check. The check finds the pair in each order, also when the registrations come at different times.
+  - The check also refuses a deeper name, for example `a.b.c` next to `a` with partitions: `b.c` is a partition of `a`.
+  - The check also refuses a storage of `a.b` for the calls without a partition while `a` has partitions, also when `a.b` has partitions. That storage publishes on `collections.a.b`.
+  - A name without a dot does not change. A dotted name without a partitioned prefix does not change. Two collections with partitions, for example `a` and `a.b`, do not change, because the partitions of `a.b` encode its name.
+  
+  PATCH (decision D23): the change refuses only a configuration that leaks events across tenants, so no caller can rely on it. Each correct configuration behaves as before.
+  
+  Migration steps:
+  
+  - When a host fails with `CollectionTopicCollisionError`, rename the plain collection, for example `a.b` to `a_b`. A name without a dot has no topic of a partition.
+  - The site: no change is necessary. It serves no collection.
+  - MiniMongo: no change is necessary. Its server serves no collection.
+  - Graph: no change is necessary. Its host gives partitions to each served collection (`examples`), and no collection has a plain storage.
+  - jarvis: no change is necessary. Its host serves no collection.
+- 0379278: Docs and tests: the rule of the retryable flag of an in-band end (CLI-58). The behavior does not change, thus this change is a PATCH of the client group (decision D13).
+  
+  - Before the stream starts, an error of a handler without a retryable flag gets the flag of its code in `ERROR_CODES` (CLI-48). Thus `UNAVAILABLE` without a flag is retryable, and the HTTP face answers 503.
+  - After the stream starts, an error ends the stream in-band. The in-band end is the `error` line of NDJSON, the `error` frame of WebSocket or the `_meta` of the MCP result.
+  - An in-band end without a retryable flag gets `retryable: false`, also when the stream gave no item. The reader can have items, and a retry can send them again.
+  - A handler gives `retryable: true` when a retry is safe. Then the in-band end is retryable too.
+  - The retry middleware of the client does not retry after an item reached the reader. Thus after the first item, the flag only tells the application.
+  - This rule agrees with the rule of a cut (CLI-48): the flag is false when the call can have had its effect.
+  - `WIRE-PROTOCOL.md` gives the rule in the section "Error codes". Tests pin it on the wire of HTTP and WebSocket, and on the HTTP, WebSocket and MCP faces of the procedures host.
+  
+  The site, MiniMongo, Graph and jarvis: no change.
+
 ## 0.18.0
 
 ### Minor Changes

package/README.md

@@ -707,7 +707,7 @@ interface ProcedureServerOptions {
   storage?: StorageConfig;
   transports?: ServerTransport[];
   events?: EventPublisherOptions | EventPublisher;   // the remote events: refer to "Remote events"
-  token?: string;                // the token that each network request presents
+  token?: string;                // the token that each request presents, except a local request
   principalOf?: PrincipalOf;     // the request hook: refer to "The request hook"
   authenticate?: (request: ServerRequest) => Principal | undefined | Promise<Principal | undefined>;
 }
@@ -735,9 +735,27 @@ const server = new ProcedureServer({
 - `principal`: the principal of the request, for example the user of a session cookie. The procedure reads it as `ctx.principal`, and its nested calls get the same principal.
 - `narrowing`: a narrower capability that the request asks for. The server narrows the capability of the call with it. A request for more has no effect.
 - An empty object accepts the request without a principal. Undefined, or an error, refuses the request with `UNAUTHORIZED`.
-- `authenticate` operates after the hook and can read `request.principal`. A request of this process (no credentials) does not go through the hook.
+- `authenticate` operates after the hook and can read `request.principal`. A local request does not go through the hook.
 - `hostPolicy({ principalOf })` gives the hook to each server of the policy.
 
+#### Local requests
+
+Each face sets the credentials of its requests, or the local marker `LOCAL_CREDENTIALS` (CLI-1). A local request comes from this application, so the token and the request hook do not apply to it.
+
+- The local faces are MCP over stdio, an SDK transport of `McpServerTransport` and `PortTransport`. The peer of stdio is the parent process. Only the holder of the other end of a port can send to it.
+- A network face never sets the marker: HTTP, WebSocket, and MCP over Streamable HTTP. The key of the marker is a symbol, so JSON, a header, a cookie or a query cannot carry it.
+- A server with a token or a request hook refuses a request without credentials with `UNAUTHORIZED`. The hook does not operate for it. Before, such a request skipped the token and the hook.
+- A call of the code of the application to `server.handle()` sets the marker itself:
+
+```typescript
+import { LOCAL_CREDENTIALS } from "@procedures/client";
+
+await server.handle({ id: "1", method, payload, metadata: {}, credentials: LOCAL_CREDENTIALS });
+```
+
+- The nested calls of a procedure do not go through the token check again. They keep the principal of their caller.
+- A `PortTransport` that a part outside the application can reach takes `credentials: {}`. Then the token applies. A `Window` is such a port.
+
 #### Cookies and CSRF
 
 A browser sends the cookies of a server by itself, also for a request that a page of another site starts. Thus a server that reads cookies trusts a request only from a named origin.