@procedures/client 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @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

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.