@ultimat3/mcp 22.5.0 → 22.6.0

package/CLAUDE.md

@@ -22,6 +22,7 @@ import. The CLI wires it.
 | `dev-server.ts` | the 13 dev tools; depends only on an injected `DevHost` |
 | `dev-host.ts` | wires `describe*` from entity/action/query/jobs into a `DevHost` |
 | `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor, and the per-caller rate limit it enforces itself |
+| `oauth-metadata.ts` | RFC 9728 protected-resource metadata + the 401 `resource_metadata` challenge (`defineAppMcp({ oauth })`); the authorization server is the app's |
 | `transport-stdio.ts` | NDJSON on stdin/stdout for `x mcp serve` |
 | `app-tools.ts` | `defineAppMcp` — a generated app's own MCP surface, one call |
 | `app-tool.ts` | the authored `tools: { name: {...} }` record → `ProjectablePrimitive` |

package/README.md

@@ -253,6 +253,19 @@ did not.
 | the body cap | `mcpHttpRoute({ bodyLimitBytes })` · `defineAppMcp({ bodyLimitBytes })` | `DEFAULT_MCP_BODY_LIMIT_BYTES`, 1 MiB |
 | the numbers | `mcpHttpRoute({ rateLimits })` · `defineAppMcp({ rateLimits })` | `MCP_RATE_LIMITS` |
 | where they are counted | `mcpHttpRoute({ rateLimitStore })` · `defineAppMcp({ rateLimitStore })` | a per-**process** memory store — N replicas behind one URL each enforce the full allowance, so a fleet passes `postgresRateLimitStore({ executor })` |
+| OAuth discovery | `mcpHttpRoute({ oauth })` · `defineAppMcp({ oauth })` | absent: the 401 is `Bearer realm="ultimate-mcp"` |
+
+### OAuth discovery (RFC 9728)
+
+`defineAppMcp({ oauth: { authorizationServers: ['https://www.example.com'] } })` (`As of 22.6.0`;
+MCP authorization spec 2025-06-18, unchanged in 2025-11-25): every 401 carries
+`WWW-Authenticate: Bearer realm="ultimate-mcp", resource_metadata="<origin>/.well-known/oauth-protected-resource<path>"`
+(`error="invalid_token"` when a token was sent), and `route.protectedResource` carries the document
+and the two paths it is served at — path-inserted per RFC 9728 §3.1 and the root — which
+`@ultimat3/cli` mounts as public `GET`s beside `POST /mcp`. `resource` defaults to the request's
+PUBLIC origin (`handle(request, { origin })`, which the boot fills from `ctx.https`) + the mount
+path; `scopes_supported` to the `scopes` map's keys. Issuers must be https (http on loopback):
+`X_MCP_OAUTH_INVALID`. The authorization server is the app's own routes.
 
 ## Resources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.5.0",
+  "version": "22.6.0",
   "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.5.0",
-    "@ultimat3/core": "22.5.0",
-    "@ultimat3/entity": "22.5.0",
-    "@ultimat3/http": "22.5.0",
-    "@ultimat3/jobs": "22.5.0",
-    "@ultimat3/policy": "22.5.0",
-    "@ultimat3/query": "22.5.0",
-    "@ultimat3/schema": "22.5.0"
+    "@ultimat3/action": "22.6.0",
+    "@ultimat3/core": "22.6.0",
+    "@ultimat3/entity": "22.6.0",
+    "@ultimat3/http": "22.6.0",
+    "@ultimat3/jobs": "22.6.0",
+    "@ultimat3/policy": "22.6.0",
+    "@ultimat3/query": "22.6.0",
+    "@ultimat3/schema": "22.6.0"
   }
 }

package/src/app-tools.ts

@@ -16,6 +16,7 @@ import { McpToolDuplicateError } from './errors';
 import { exposedPrimitives } from './exposed';
 import { toolsFrom, toolsListed } from './from-action';
 import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
+import type { McpOAuth } from './oauth-metadata';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
 import type { AnyMcpTool, McpVerbClass } from './registry';
@@ -118,6 +119,17 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    * `postgresRateLimitStore({ executor })` the web role takes.
    */
   readonly rateLimitStore?: RateLimitStore | undefined;
+  /**
+   * OAuth discovery for remote MCP clients (the MCP authorization spec, RFC 9728): the route's 401
+   * says `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp"`,
+   * and the boot serves that document (and the root one) naming `authorizationServers`. The
+   * authorization server — consent, `/oauth/token` — is the app's own routes.
+   *
+   * ```ts
+   * oauth: { authorizationServers: ['https://www.example.com'], resourceName: 'Example' },
+   * ```
+   */
+  readonly oauth?: McpOAuth | undefined;
 }
 
 export interface AppMcp {
@@ -201,6 +213,9 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
           ...(input.bodyLimitBytes !== undefined ? { bodyLimitBytes: input.bodyLimitBytes } : {}),
           ...(input.rateLimits !== undefined ? { rateLimits: input.rateLimits } : {}),
           ...(input.rateLimitStore !== undefined ? { rateLimitStore: input.rateLimitStore } : {}),
+          ...(input.oauth === undefined
+            ? {}
+            : { oauth: input.oauth, scopes: Object.keys(input.scopes ?? {}) }),
         });
 
   return { server, tools: projected, route };

package/src/errors.ts

@@ -23,6 +23,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_GROUP_CONFLICT',
   'X_MCP_SURFACE_INVALID',
   'X_MCP_LIST_PARAMS_INVALID',
+  'X_MCP_OAUTH_INVALID',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -47,6 +48,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_GROUP_CONFLICT: 'two resource groups claim one MCP tool',
   X_MCP_SURFACE_INVALID: 'the MCP meta surface is declared inconsistently',
   X_MCP_LIST_PARAMS_INVALID: "a tool's listParams names a key its own input does not accept",
+  X_MCP_OAUTH_INVALID: 'the MCP oauth block cannot be published as protected-resource metadata',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -417,3 +419,14 @@ export class McpRateLimitedError extends UltimateError {
     });
   }
 }
+
+/** `defineAppMcp({ oauth })` refused at boot — see `oauth-metadata.ts`. */
+export class McpOAuthInvalidError extends UltimateError {
+  constructor(reason: string) {
+    super({
+      code: 'X_MCP_OAUTH_INVALID',
+      cause: `defineAppMcp({ oauth }) cannot be published as protected-resource metadata: ${reason}`,
+      fix: "defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL; resource and resourceDocumentation, when set, absolute URLs with no fragment",
+    });
+  }
+}

package/src/index.ts

@@ -64,6 +64,7 @@ export {
   McpArgsInvalidError,
   McpBodyTooLargeError,
   McpNotBranchDbError,
+  McpOAuthInvalidError,
   McpProtocolError,
   McpQueryRejectedError,
   McpRateLimitedError,
@@ -111,6 +112,13 @@ export {
   META_TOOL_NAMES,
   oneLineParams,
 } from './meta-surface';
+export type { McpOAuth } from './oauth-metadata';
+export {
+  metadataPaths,
+  metadataUrlFor,
+  PROTECTED_RESOURCE_WELL_KNOWN,
+  protectedResourceMetadata,
+} from './oauth-metadata';
 export type { ListedPrimitive } from './projectable';
 export { asProjectable } from './projectable';
 export type { QueryLimits, QueryResult, QueryRows } from './query-limits';
@@ -156,6 +164,8 @@ export type { CreateMcpServerInput, McpWire } from './server';
 export { createMcpServer, McpServer } from './server';
 export type {
   McpHttpTransportInput,
+  McpProtectedResource,
+  McpRequestOrigin,
   McpRouteDescriptor,
   ResolvedToken,
 } from './transport-http';

package/src/oauth-metadata.ts

@@ -0,0 +1,114 @@
+// OAuth 2.0 Protected Resource Metadata (RFC 9728) for the MCP endpoint — the framework half of
+// the MCP authorization spec (2025-06-18, unchanged in 2025-11-25): a 401 names where the metadata
+// lives (`WWW-Authenticate: Bearer resource_metadata="…"`), and the metadata names the
+// authorization server(s) a client goes to for a token. The authorization server itself is the
+// APP's — its consent page, its token endpoint, its revocation list — never this package's.
+
+import { McpOAuthInvalidError } from './errors';
+
+/** The well-known suffix RFC 9728 §3 defines. */
+export const PROTECTED_RESOURCE_WELL_KNOWN = '/.well-known/oauth-protected-resource';
+
+export interface McpOAuth {
+  /**
+   * Issuer identifiers of the authorization servers that mint tokens this endpoint accepts
+   * (`authorization_servers`). At least one; an absolute https URL, or http on localhost.
+   */
+  readonly authorizationServers: readonly string[];
+  /**
+   * The canonical URL of this MCP endpoint (RFC 8707 `resource`), e.g.
+   * `https://www.example.com/mcp`. Omitted, it is the request's own public origin + the mount
+   * path — right for one image deployed behind many hosts.
+   */
+  readonly resource?: string;
+  /** `scopes_supported`. Omitted, the keys of `defineAppMcp({ scopes })`. */
+  readonly scopesSupported?: readonly string[];
+  /** `resource_name` — shown by a client's consent screen. */
+  readonly resourceName?: string;
+  /** `resource_documentation` — an absolute URL. */
+  readonly resourceDocumentation?: string;
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/** https anywhere, http only on loopback (RFC 9728 §3.3, OAuth 2.1 §1.5), and never a fragment. */
+function isIssuerUrl(value: string): boolean {
+  const url = URL.parse(value);
+  if (url === null || url.hash !== '') return false;
+  return url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname));
+}
+
+/** At `defineAppMcp`, never on a request. */
+export function assertMcpOAuth(oauth: McpOAuth): void {
+  if (oauth.authorizationServers.length === 0) {
+    throw new McpOAuthInvalidError('authorizationServers is empty');
+  }
+  for (const issuer of oauth.authorizationServers) {
+    if (!isIssuerUrl(issuer)) {
+      throw new McpOAuthInvalidError(
+        `${JSON.stringify(issuer)} is not an absolute https issuer URL`,
+      );
+    }
+  }
+  for (const key of ['resource', 'resourceDocumentation'] as const) {
+    const value = oauth[key];
+    if (value !== undefined && !isIssuerUrl(value)) {
+      throw new McpOAuthInvalidError(
+        `${key} ${JSON.stringify(value)} is not an absolute https URL`,
+      );
+    }
+  }
+}
+
+/** The resource this request addresses: the declared one, else `<origin><path>`. */
+export function resourceUrl(oauth: McpOAuth, origin: string, path: string): string {
+  return oauth.resource ?? `${origin.replace(/\/+$/, '')}${path}`;
+}
+
+/**
+ * RFC 9728 §3.1: the well-known suffix INSERTED between the host and the resource's path —
+ * `https://x.test/mcp` → `https://x.test/.well-known/oauth-protected-resource/mcp`.
+ */
+export function metadataUrlFor(resource: string): string {
+  const url = new URL(resource);
+  const path = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+  return `${url.origin}${PROTECTED_RESOURCE_WELL_KNOWN}${path}`;
+}
+
+/** The two paths a host serves the document at: path-inserted (RFC 9728), and the root. */
+export function metadataPaths(mountPath: string): readonly string[] {
+  const inserted = `${PROTECTED_RESOURCE_WELL_KNOWN}${mountPath === '/' ? '' : mountPath}`;
+  return inserted === PROTECTED_RESOURCE_WELL_KNOWN
+    ? [PROTECTED_RESOURCE_WELL_KNOWN]
+    : [inserted, PROTECTED_RESOURCE_WELL_KNOWN];
+}
+
+/** The metadata document for `resource`. Keys in RFC 9728 §2's names. */
+export function protectedResourceMetadata(
+  oauth: McpOAuth,
+  resource: string,
+  scopes: readonly string[],
+): Record<string, unknown> {
+  const supported = oauth.scopesSupported ?? scopes;
+  return {
+    resource,
+    authorization_servers: [...oauth.authorizationServers],
+    bearer_methods_supported: ['header'],
+    ...(supported.length === 0 ? {} : { scopes_supported: [...supported].sort() }),
+    ...(oauth.resourceName === undefined ? {} : { resource_name: oauth.resourceName }),
+    ...(oauth.resourceDocumentation === undefined
+      ? {}
+      : { resource_documentation: oauth.resourceDocumentation }),
+  };
+}
+
+/**
+ * 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).
+ */
+export function bearerChallenge(metadataUrl: string | undefined, tokenSent: boolean): string {
+  const params = ['realm="ultimate-mcp"'];
+  if (tokenSent) params.push('error="invalid_token"');
+  if (metadataUrl !== undefined) params.push(`resource_metadata="${metadataUrl}"`);
+  return `Bearer ${params.join(', ')}`;
+}

package/src/transport-http.ts

@@ -24,6 +24,15 @@ import { finiteCount, readWithinLimit, systemClock } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
 import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
 import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
+import type { McpOAuth } from './oauth-metadata';
+import {
+  assertMcpOAuth,
+  bearerChallenge,
+  metadataPaths,
+  metadataUrlFor,
+  protectedResourceMetadata,
+  resourceUrl,
+} from './oauth-metadata';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
 import type { JsonRpcResponse } from './wire';
@@ -75,6 +84,28 @@ export interface McpHttpTransportInput {
   readonly rateLimitStore?: RateLimitStore | undefined;
   /** The one clock the buckets refill on. Defaulted, never read inline, so a test can freeze it. */
   readonly clock?: Clock | undefined;
+  /**
+   * Publish RFC 9728 protected-resource metadata and name it in every 401's `WWW-Authenticate` —
+   * the discovery an OAuth-capable MCP client (a remote connector) starts from. Absent, the 401
+   * says `Bearer realm="ultimate-mcp"` as it always did.
+   */
+  readonly oauth?: McpOAuth | undefined;
+  /** `scopes_supported` when `oauth.scopesSupported` is not stated: the app's scope names. */
+  readonly scopes?: readonly string[] | undefined;
+}
+
+/** How the host saw the request — what a bare `Request` behind a TLS-terminating proxy cannot say. */
+export interface McpRequestOrigin {
+  /** The PUBLIC origin, `https://www.example.com`. Defaults to the request URL's own. */
+  readonly origin?: string | undefined;
+}
+
+/** The metadata half of an `oauth` route: where to serve it and what to answer. */
+export interface McpProtectedResource {
+  /** `/.well-known/oauth-protected-resource/mcp` and the root one. `GET`, public. */
+  readonly paths: readonly string[];
+  /** The document, for the public origin the request arrived on. */
+  document(origin: string): Record<string, unknown>;
 }
 
 export interface McpRouteDescriptor {
@@ -84,7 +115,9 @@ export interface McpRouteDescriptor {
   rateLimitClass(body: unknown): McpVerbClass;
   /** Requests per minute per caller, by class — what `handle` actually spends against. */
   readonly limits: Readonly<Record<McpVerbClass, number>>;
-  handle(request: Request): Promise<Response>;
+  /** Present exactly when the route was built with `oauth`. */
+  readonly protectedResource?: McpProtectedResource;
+  handle(request: Request, seen?: McpRequestOrigin): Promise<Response>;
 }
 
 const JSON_HEADERS = { 'content-type': 'application/json' } as const;
@@ -118,23 +151,41 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   });
 
   const path = input.path ?? '/mcp';
+  const oauth = input.oauth;
+  if (oauth !== undefined) assertMcpOAuth(oauth);
+  const scopes = input.scopes ?? [];
+  const resourceOf = (request: Request, seen: McpRequestOrigin | undefined): string | undefined =>
+    oauth === undefined
+      ? undefined
+      : resourceUrl(oauth, seen?.origin ?? new URL(request.url).origin, path);
 
   return {
     method: 'POST',
     path,
     limits,
     rateLimitClass: (body) => server.classify(body),
+    ...(oauth === undefined
+      ? {}
+      : {
+          protectedResource: {
+            paths: metadataPaths(path),
+            document: (origin: string) =>
+              protectedResourceMetadata(oauth, resourceUrl(oauth, origin, path), scopes),
+          },
+        }),
 
-    async handle(request: Request): Promise<Response> {
+    async handle(request: Request, seen?: McpRequestOrigin): Promise<Response> {
       // Every authentication answer lands BEFORE the body is read. Parsing first meant a caller
       // holding a rejected token still learned whether its JSON was well formed — `400 parse
       // error` for one payload and `401` for the next is exactly the oracle the 401 exists to
       // remove, and it costs nothing to close: the body is not an input to any of these.
+      const resource = resourceOf(request, seen);
+      const metadataUrl = resource === undefined ? undefined : metadataUrlFor(resource);
       const token = bearerToken(request);
-      if (token === null) return unauthorized();
+      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false));
 
       const resolved = await input.resolveToken(token);
-      if (resolved === null) return unauthorized();
+      if (resolved === null) return unauthorized(bearerChallenge(metadataUrl, true));
       if (!isAgentActor(resolved.actor)) return notAnAgent();
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
@@ -253,7 +304,7 @@ function notAnAgent(): Response {
   );
 }
 
-function unauthorized(): Response {
+function unauthorized(challenge: string): Response {
   return new Response(
     JSON.stringify({
       code: 'X_MCP_PROTOCOL',
@@ -262,7 +313,7 @@ function unauthorized(): Response {
     }),
     {
       status: 401,
-      headers: { ...JSON_HEADERS, 'www-authenticate': 'Bearer realm="ultimate-mcp"' },
+      headers: { ...JSON_HEADERS, 'www-authenticate': challenge },
     },
   );
 }