@ultimat3/mcp 24.0.0 → 25.0.0

package/src/transport-http.ts

@@ -21,9 +21,9 @@
 
 import type { Actor, Clock } from '@ultimat3/core';
 import { finiteCount, readWithinLimit, systemClock } from '@ultimat3/core';
-import type { Bucket, RateLimitStore } from '@ultimat3/http';
-import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
-import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
+import type { Bucket, RequestFacts as McpRequestFacts, RateLimitStore } from '@ultimat3/http';
+import { memoryRateLimitStore, requestFacts, toBucket } from '@ultimat3/http';
+import { McpBodyTooLargeError, McpRateLimitedError } from './errors-transport';
 import type { McpOAuth } from './oauth-metadata';
 import {
   assertMcpOAuth,
@@ -43,7 +43,7 @@ import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './w
 /**
  * The same 1 MiB `@ultimat3/http`'s `bodyLimitBytes` defaults to. This descriptor is driven from a
  * bare `Request` and never passes through that pipeline, so without a cap here Bun's 128 MiB
- * default was the only ceiling — and `x mcp serve` and `createServer` both pass no
+ * default was the only ceiling — and `x mcp serve` and `httpServer` both pass no
  * `maxRequestBodySize`.
  */
 export const DEFAULT_MCP_BODY_LIMIT_BYTES = 1_048_576;
@@ -79,10 +79,16 @@ export interface ResolvedToken {
 export interface McpHttpTransportInput {
   readonly server: McpServer;
   /**
-   * Resolve an OAuth bearer / personal token to a caller. The framework supplies the token
-   * string only — credential storage belongs to `@ultimat3/policy` and the app, never here.
+   * Resolve an OAuth bearer / personal token to a caller. The framework supplies the token and
+   * how the request arrived (`McpRequestFacts`: the host-resolved address, user agent, `Origin`,
+   * path) — so a token can be bound to a network or refused from a browser origin. Credential
+   * storage belongs to `@ultimat3/policy` and the app, never here. A one-argument resolver is
+   * still one: the facts are an extra argument it may ignore.
    */
-  resolveToken(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
+  resolveToken(
+    token: string,
+    facts: McpRequestFacts,
+  ): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Route path. Overridable so an app can mount a second, app-scoped surface. */
   readonly path?: string;
   /** Bytes this transport will hold for one request. Defaults to `DEFAULT_MCP_BODY_LIMIT_BYTES`. */
@@ -231,24 +237,42 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // An address that has spent its failures is refused BEFORE the credential store is asked:
       // counting only after the fact turned a 401 into a 429 and still answered a valid guess.
       const address = seen?.address;
+      // Built once per request: the resolver's second argument and every refusal's audit facts.
+      // The address inside is the host's answer (`seen.address`), never a header read here.
+      const facts = requestFacts({ headers: request.headers, url: request.url, address });
+      const audit = server.audit;
       const exhausted = await failures.refusing(address);
-      if (exhausted !== undefined) return exhausted;
+      if (exhausted !== undefined) {
+        audit.authRefused('throttled', exhausted.status, facts);
+        return exhausted;
+      }
+      // A failure spends the address's allowance; the 429 wins when that one did not fit.
+      const refuse = async (
+        reason: 'missing-token' | 'rejected-token',
+        challenge: string,
+      ): Promise<Response> => {
+        const throttledNow = await failures.spend(address);
+        const response = throttledNow ?? unauthorized(challenge);
+        audit.authRefused(
+          throttledNow === undefined ? reason : 'throttled',
+          response.status,
+          facts,
+        );
+        return response;
+      };
       const token = bearerToken(request);
       if (token === null) {
-        return (
-          (await failures.spend(address)) ??
-          unauthorized(bearerChallenge(metadataUrl, false, challengeScopes))
-        );
+        return refuse('missing-token', bearerChallenge(metadataUrl, false, challengeScopes));
       }
 
-      const resolved = await input.resolveToken(token);
+      const resolved = await input.resolveToken(token, facts);
       if (resolved === null) {
-        return (
-          (await failures.spend(address)) ??
-          unauthorized(bearerChallenge(metadataUrl, true, challengeScopes))
-        );
+        return refuse('rejected-token', bearerChallenge(metadataUrl, true, challengeScopes));
+      }
+      if (!isAgentActor(resolved.actor)) {
+        audit.authRefused('not-an-agent', 403, facts);
+        return notAnAgent();
       }
-      if (!isAgentActor(resolved.actor)) return notAnAgent();
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
       // WHILE the bytes arrive, or a `transfer-encoding: chunked` payload is materialised in full

package/src/transport-stdio.ts

@@ -9,7 +9,7 @@
 // stderr and this file never calls `console.log`.
 
 import { finiteCount } from '@ultimat3/core';
-import { McpBodyTooLargeError } from './errors';
+import { McpBodyTooLargeError } from './errors-transport';
 import type { McpCaller } from './registry';
 import type { McpServer } from './server';
 import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './wire';

package/src/type-pins.ts

@@ -0,0 +1,52 @@
+// Compile-time pins for this package's public types. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level claim written in one can never fail. This module emits nothing and exports nothing
+// anybody imports — a regression here is a build error, the only enforcement that counts.
+
+import type {
+  McpListParams as CoreListParams,
+  McpAnnotationHints,
+  McpExposureDeclaration,
+} from '@ultimat3/core';
+import type { ProjectablePrimitive } from './from-action';
+import type { McpListParams } from './list-params';
+import type { McpToolAnnotations } from './registry';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+type Projected = NonNullable<ProjectablePrimitive['mcp']>;
+
+/**
+ * 25.0.0: the projection reads core's ONE `mcp` block. `McpExposure` restated it here, a field
+ * looser (`expose?`) than the block an action or query is held to; a twin coming back as a
+ * different shape flips this to `false`.
+ */
+export type _ProjectionReadsCoresBlock = Assert<Identical<Projected, McpExposureDeclaration>>;
+
+/**
+ * 25.0.0 (plan 101, M4): a projected tool is named by its primitive's `name` and by nothing
+ * else. `McpExposure.name` was a second naming field no declaration could set; one coming back
+ * on core's block flips this to `false`.
+ */
+export type _McpBlockCarriesNoName = Assert<Equals<Extract<keyof Projected, 'name'>, never>>;
+
+/**
+ * The tool's own wire types (`McpTool.annotations`, `McpTool.listParams`) are what the block's
+ * fields become, so they must stay the block's shapes exactly: a hint or a whitelist key added
+ * on one side only is a declaration the other silently drops.
+ */
+export type _ToolAnnotationsAreTheBlocks = Assert<
+  Identical<McpToolAnnotations, McpAnnotationHints>
+>;
+export type _ToolListParamsAreTheBlocks = Assert<Identical<McpListParams, CoreListParams>>;

package/src/wire.ts

@@ -113,3 +113,20 @@ export function paramsOf(req: JsonRpcRequest): Record<string, unknown> | null {
   if (typeof req.params !== 'object' || req.params === null) return null;
   return req.params as Record<string, unknown>;
 }
+
+/**
+ * Which wire one message arrived on, so a refusal can name the unit THAT transport counts in.
+ * `handle` is transport-independent and stays so — this is a hint for the wording of one fix, never
+ * a branch in dispatch. HTTP carries its mounted path because `mcpHttpRoute({ path })` is a knob:
+ * a batch refusal that told every client to retry `POST /mcp` was wrong for an app mounted at
+ * `/app-mcp`, which is how this came to be threaded rather than spelled.
+ */
+export type McpWire =
+  | { readonly transport: 'http'; readonly path: string }
+  | { readonly transport: 'stdio' };
+
+/** The unit a transport counts one request in — or the neutral word when no wire said. */
+export const messageUnitOf = (wire: McpWire | undefined): string => {
+  if (wire === undefined) return 'message';
+  return wire.transport === 'http' ? `POST ${wire.path}` : 'line';
+};