@ultimat3/mcp 22.6.2 → 22.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.6.2",
+  "version": "22.7.1",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.6.2",
-    "@ultimat3/core": "22.6.2",
-    "@ultimat3/entity": "22.6.2",
-    "@ultimat3/http": "22.6.2",
-    "@ultimat3/jobs": "22.6.2",
-    "@ultimat3/policy": "22.6.2",
-    "@ultimat3/query": "22.6.2",
-    "@ultimat3/schema": "22.6.2"
+    "@ultimat3/action": "22.7.1",
+    "@ultimat3/core": "22.7.1",
+    "@ultimat3/entity": "22.7.1",
+    "@ultimat3/http": "22.7.1",
+    "@ultimat3/jobs": "22.7.1",
+    "@ultimat3/policy": "22.7.1",
+    "@ultimat3/query": "22.7.1",
+    "@ultimat3/schema": "22.7.1"
   }
 }

package/src/oauth-metadata.ts

@@ -89,7 +89,7 @@ export function protectedResourceMetadata(
   resource: string,
   scopes: readonly string[],
 ): Record<string, unknown> {
-  const supported = oauth.scopesSupported ?? scopes;
+  const supported = supportedScopes(oauth, scopes);
   return {
     resource,
     authorization_servers: [...oauth.authorizationServers],
@@ -102,13 +102,43 @@ export function protectedResourceMetadata(
   };
 }
 
+/** `scopes_supported` and the challenge's `scope`: the stated list, else the app's scope names. */
+export function supportedScopes(oauth: McpOAuth, scopes: readonly string[]): readonly string[] {
+  return [...(oauth.scopesSupported ?? scopes)].sort();
+}
+
+/** RFC 6749 §3.3 `scope-token = 1*( %x21 / %x23-5B / %x5D-7E )`. */
+const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+
+/**
+ * At construction, beside `assertMcpOAuth`: every scope the challenge will name must be a
+ * scope-token. A space would split one scope into two in `scope="a b"`, and a quote or backslash
+ * would end the quoted-string early — a header a client parses into something nobody declared.
+ */
+export function assertScopeTokens(scopes: readonly string[]): void {
+  for (const scope of scopes) {
+    if (!SCOPE_TOKEN.test(scope)) {
+      throw new McpOAuthInvalidError(
+        `scope ${JSON.stringify(scope)} is not an RFC 6749 scope-token (printable ASCII, no space, quote or backslash)`,
+      );
+    }
+  }
+}
+
 /**
  * The challenge a 401 carries. `error="invalid_token"` only when a token WAS sent (RFC 6750
- * §3.1: a request with no credential gets no error code).
+ * §3.1: a request with no credential gets no error code). `scope` names what the resource
+ * supports (RFC 6750 §3, MCP authorization 2025-06-18 / 2025-11-25 "scope selection"), so a
+ * client can ask for it without first fetching the metadata; omitted when there is none.
  */
-export function bearerChallenge(metadataUrl: string | undefined, tokenSent: boolean): string {
+export function bearerChallenge(
+  metadataUrl: string | undefined,
+  tokenSent: boolean,
+  scopes: readonly string[] = [],
+): string {
   const params = ['realm="ultimate-mcp"'];
   if (tokenSent) params.push('error="invalid_token"');
   if (metadataUrl !== undefined) params.push(`resource_metadata="${metadataUrl}"`);
+  if (scopes.length > 0) params.push(`scope="${scopes.join(' ')}"`);
   return `Bearer ${params.join(', ')}`;
 }

package/src/transport-http.ts

@@ -27,11 +27,13 @@ import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
 import type { McpOAuth } from './oauth-metadata';
 import {
   assertMcpOAuth,
+  assertScopeTokens,
   bearerChallenge,
   metadataPaths,
   metadataUrlFor,
   protectedResourceMetadata,
   resourceUrl,
+  supportedScopes,
 } from './oauth-metadata';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
@@ -120,7 +122,14 @@ export interface McpRouteDescriptor {
   handle(request: Request, seen?: McpRequestOrigin): Promise<Response>;
 }
 
-const JSON_HEADERS = { 'content-type': 'application/json' } as const;
+/**
+ * Every answer on this route is one caller's: a 401 challenge, a refusal, a JSON-RPC result for
+ * the token that asked. `no-store` on all of them (RFC 6750 §3 / RFC 6749 §5.1 for the auth
+ * answers), stated HERE because the descriptor is also served bare by `x mcp serve`, where no
+ * pipeline stage decides a cache header for it.
+ */
+const NO_STORE_HEADERS = { 'cache-control': 'no-store' } as const;
+const JSON_HEADERS = { 'content-type': 'application/json', ...NO_STORE_HEADERS } as const;
 
 export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   const { server } = input;
@@ -154,6 +163,9 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   const oauth = input.oauth;
   if (oauth !== undefined) assertMcpOAuth(oauth);
   const scopes = input.scopes ?? [];
+  // What the 401 names in `scope="…"` — only on an `oauth` route, the one a client discovers from.
+  const challengeScopes = oauth === undefined ? [] : supportedScopes(oauth, scopes);
+  assertScopeTokens(challengeScopes);
   const resourceOf = (request: Request, seen: McpRequestOrigin | undefined): string | undefined =>
     oauth === undefined
       ? undefined
@@ -182,10 +194,11 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       const resource = resourceOf(request, seen);
       const metadataUrl = resource === undefined ? undefined : metadataUrlFor(resource);
       const token = bearerToken(request);
-      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false));
+      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false, challengeScopes));
 
       const resolved = await input.resolveToken(token);
-      if (resolved === null) return unauthorized(bearerChallenge(metadataUrl, true));
+      if (resolved === null)
+        return unauthorized(bearerChallenge(metadataUrl, true, challengeScopes));
       if (!isAgentActor(resolved.actor)) return notAnAgent();
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
@@ -253,7 +266,7 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // not a spelled `/mcp`.
       const response = await server.handle(body, caller, { transport: 'http', path });
       // A notification has no response. 202 with an empty body is the MCP-correct answer.
-      if (response === null) return new Response(null, { status: 202 });
+      if (response === null) return new Response(null, { status: 202, headers: NO_STORE_HEADERS });
       // JSON-RPC errors are 200s: the transport succeeded, the call did not. Only a
       // malformed envelope (below) is an HTTP-level failure.
       const status = response.error?.code === INVALID_REQUEST && response.id === null ? 400 : 200;