@absolutejs/mcp 0.7.0 → 0.9.0

package/README.md

@@ -1,5 +1,9 @@
 # @absolutejs/mcp
 
+MCP tool discovery preserves the OpenID AuthZEN COAZ `coaz` marker and
+`x-coaz-mapping` JSON Schema extension end to end. Use `@absolutejs/policy` to
+validate and evaluate the mapping before dispatching an authorized tool call.
+
 Serve a remote [Model Context Protocol](https://modelcontextprotocol.io) endpoint
 — streamable HTTP, stateless — from a tool/prompt/resource registry. You supply
 **which** tools to expose and **how** to authorize a request into a caller; the
@@ -309,6 +313,35 @@ app.use(mcpServer({ path: "/mcp" /* member */ })).use(
 
 Only one endpoint per app should set `serveRootMetadata` (the un-suffixed alias).
 
+## OAuth-native MCP client
+
+`createMcpOAuthProvider` handles the current MCP authorization flow without
+coupling to an identity vendor: RFC 9728 protected-resource discovery, OAuth or
+OIDC authorization-server discovery, Client ID Metadata Document identifiers,
+PKCE S256, resource indicators, refresh rotation, incremental scope challenges,
+and optional DPoP proofs. The host owns the user interaction and token store.
+
+```ts
+const authorization = createMcpOAuthProvider({
+  endpoint: "https://tools.example/mcp",
+  clientId: "https://my-agent.example/oauth-client.json",
+  redirectUri: "https://my-agent.example/oauth/callback",
+  fetch: egress.fetch,
+  store: durableTokenStore,
+  onAuthorize: showConsentAndWaitForCallback,
+});
+
+const client = createMcpClient({
+  url: "https://tools.example/mcp",
+  authorization,
+});
+```
+
+The client retries a 401 only once and only after the authorization provider
+reports success. Metadata fetches require HTTPS, reject redirects, enforce byte
+limits, verify issuer/resource identity, and use the injected fetch so production
+deployments can route discovery through `@absolutejs/egress`.
+
 ## License
 
 Business Source License 1.1 — see [LICENSE](./LICENSE). Converts to Apache 2.0

package/dist/index.js

@@ -131,11 +131,13 @@ var createMcpClient = (options) => {
   let protocolVersion = options.protocolVersion ?? DEFAULT_PROTOCOL;
   let sessionId = null;
   let nextId = 1;
+  const authorizationHeaders = (method) => options.authorization?.headers({ method, url: options.url }) ?? {};
   const respond = async (id, result) => {
     const headers = {
       "content-type": "application/json",
       "mcp-protocol-version": protocolVersion,
-      ...options.headers
+      ...options.headers,
+      ...await authorizationHeaders("POST")
     };
     if (sessionId !== null)
       headers["mcp-session-id"] = sessionId;
@@ -167,21 +169,38 @@ var createMcpClient = (options) => {
         accept: "application/json, text/event-stream",
         "content-type": "application/json",
         "mcp-protocol-version": protocolVersion,
-        ...options.headers
+        ...options.headers,
+        ...await authorizationHeaders("POST")
       };
       if (sessionId !== null)
         headers["mcp-session-id"] = sessionId;
-      const response = await doFetch(options.url, {
-        body: JSON.stringify({
-          id: nextId++,
-          jsonrpc: "2.0",
-          method,
-          ...params === undefined ? {} : { params }
-        }),
+      const requestBody = JSON.stringify({
+        id: nextId++,
+        jsonrpc: "2.0",
+        method,
+        ...params === undefined ? {} : { params }
+      });
+      let response = await doFetch(options.url, {
+        body: requestBody,
         headers,
         method: "POST",
         signal: controller.signal
       });
+      if (response.status === 401 && options.authorization?.onUnauthorized) {
+        const retry = await options.authorization.onUnauthorized({
+          method: "POST",
+          response,
+          url: options.url
+        });
+        if (retry) {
+          response = await doFetch(options.url, {
+            body: requestBody,
+            headers: { ...headers, ...await authorizationHeaders("POST") },
+            method: "POST",
+            signal: controller.signal
+          });
+        }
+      }
       const captured = response.headers.get("mcp-session-id");
       if (captured)
         sessionId = captured;
@@ -209,7 +228,8 @@ var createMcpClient = (options) => {
     const headers = {
       "content-type": "application/json",
       "mcp-protocol-version": protocolVersion,
-      ...options.headers
+      ...options.headers,
+      ...await authorizationHeaders("POST")
     };
     if (sessionId !== null)
       headers["mcp-session-id"] = sessionId;
@@ -245,6 +265,7 @@ var createMcpClient = (options) => {
       const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
       collected.push(...tools.filter(isRecord).map((tool) => ({
         annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
+        coaz: typeof tool.coaz === "boolean" ? tool.coaz : undefined,
         description: typeof tool.description === "string" ? tool.description : undefined,
         inputSchema: isRecord(tool.inputSchema) ? tool.inputSchema : undefined,
         name: typeof tool.name === "string" ? tool.name : "",
@@ -285,6 +306,283 @@ var createMcpClient = (options) => {
   };
   return { callTool, initialize, listResources, listTools, ping, readResource };
 };
+// src/oauth.ts
+var splitChallenges = (value) => {
+  const entries = [];
+  let quoted = false;
+  let start = 0;
+  for (let index = 0;index < value.length; index += 1) {
+    const character = value[index];
+    if (character === '"' && value[index - 1] !== "\\")
+      quoted = !quoted;
+    if (character === "," && !quoted) {
+      entries.push(value.slice(start, index).trim());
+      start = index + 1;
+    }
+  }
+  entries.push(value.slice(start).trim());
+  return entries;
+};
+var parseMcpAuthorizationChallenge = (value) => {
+  if (!value)
+    return;
+  const firstSpace = value.indexOf(" ");
+  const scheme = firstSpace < 0 ? value : value.slice(0, firstSpace);
+  if (scheme.toLowerCase() !== "bearer" && scheme.toLowerCase() !== "dpop")
+    return;
+  const parameters = new Map;
+  for (const entry of splitChallenges(firstSpace < 0 ? "" : value.slice(firstSpace + 1))) {
+    const separator = entry.indexOf("=");
+    if (separator < 1)
+      continue;
+    const key = entry.slice(0, separator).trim().toLowerCase();
+    const raw = entry.slice(separator + 1).trim();
+    parameters.set(key, raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1).replaceAll("\\\"", '"') : raw);
+  }
+  return {
+    scheme,
+    resourceMetadataUrl: parameters.get("resource_metadata"),
+    scopes: parameters.get("scope")?.split(" ").filter(Boolean) ?? [],
+    error: parameters.get("error")
+  };
+};
+var endpointMetadataPath = (endpoint) => `/.well-known/oauth-protected-resource${endpoint.pathname === "/" ? "" : endpoint.pathname}`;
+var fetchJson = async (url, fetcher, maxBytes) => {
+  const target = new URL(url);
+  if (target.protocol !== "https:")
+    throw new Error("OAuth metadata requires HTTPS");
+  const response = await fetcher(target, {
+    headers: { accept: "application/json" },
+    redirect: "error"
+  });
+  if (!response.ok)
+    throw new Error(`OAuth metadata discovery failed with ${response.status}`);
+  const declared = Number(response.headers.get("content-length") ?? "0");
+  if (declared > maxBytes)
+    throw new Error("OAuth metadata exceeds byte limit");
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > maxBytes)
+    throw new Error("OAuth metadata exceeds byte limit");
+  return JSON.parse(new TextDecoder().decode(bytes));
+};
+var discoverMcpAuthorization = async ({
+  endpoint,
+  fetch: fetcher,
+  resourceMetadataUrl,
+  maxMetadataBytes = 64 * 1024
+}) => {
+  const target = new URL(endpoint);
+  const resourceUrl = resourceMetadataUrl ?? new URL(endpointMetadataPath(target), target.origin).toString();
+  const resource = await fetchJson(resourceUrl, fetcher, maxMetadataBytes);
+  if (resource.resource !== endpoint)
+    throw new Error("Protected resource metadata has the wrong resource identifier");
+  const issuer = resource.authorization_servers?.[0];
+  if (!issuer)
+    throw new Error("Protected resource metadata has no authorization server");
+  const issuerUrl = new URL(issuer);
+  if (issuerUrl.protocol !== "https:")
+    throw new Error("Authorization server issuer requires HTTPS");
+  const candidates = [
+    new URL("/.well-known/oauth-authorization-server", issuerUrl).toString(),
+    new URL("/.well-known/openid-configuration", issuerUrl).toString()
+  ];
+  let authorizationServer;
+  for (const candidate of candidates) {
+    try {
+      const metadata = await fetchJson(candidate, fetcher, maxMetadataBytes);
+      if (metadata.issuer === issuer) {
+        authorizationServer = metadata;
+        break;
+      }
+    } catch {}
+  }
+  if (!authorizationServer)
+    throw new Error("Authorization server discovery failed");
+  return { resource, authorizationServer, resourceMetadataUrl: resourceUrl };
+};
+var random = (bytes = 32) => Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("base64url");
+var challengeFor = async (verifier) => Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))).toString("base64url");
+var createMcpAuthorizationRequest = async ({
+  discovery,
+  clientId,
+  redirectUri,
+  scopes
+}) => {
+  if (!discovery.authorizationServer.code_challenge_methods_supported?.includes("S256"))
+    throw new Error("Authorization server does not advertise PKCE S256");
+  const codeVerifier = random(48);
+  const state = random(24);
+  const url = new URL(discovery.authorizationServer.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("code_challenge", await challengeFor(codeVerifier));
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("resource", discovery.resource.resource);
+  url.searchParams.set("state", state);
+  if (scopes.length)
+    url.searchParams.set("scope", scopes.join(" "));
+  return { authorizationUrl: url.toString(), codeVerifier, state };
+};
+var parseTokens = (value, resource, now) => {
+  if (!value || typeof value !== "object")
+    throw new Error("Malformed OAuth token response");
+  const body = value;
+  if (typeof body.access_token !== "string")
+    throw new Error("OAuth response has no access token");
+  return {
+    accessToken: body.access_token,
+    tokenType: body.token_type === "DPoP" ? "DPoP" : "Bearer",
+    ...typeof body.expires_in === "number" ? { expiresAt: now + body.expires_in * 1000 } : {},
+    ...typeof body.refresh_token === "string" ? { refreshToken: body.refresh_token } : {},
+    scopes: typeof body.scope === "string" ? body.scope.split(" ").filter(Boolean) : [],
+    resource
+  };
+};
+var tokenRequest = async ({
+  endpoint,
+  fetch: fetcher,
+  params,
+  dpopProof,
+  now,
+  resource
+}) => {
+  const response = await fetcher(endpoint, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      ...dpopProof ? { dpop: dpopProof } : {}
+    },
+    body: params.toString()
+  });
+  if (!response.ok)
+    throw new Error(`OAuth token exchange failed with ${response.status}`);
+  return parseTokens(await response.json(), resource, now);
+};
+var createMemoryMcpOAuthTokenStore = () => {
+  const tokens = new Map;
+  return {
+    load: async (resource) => tokens.get(resource),
+    save: async (value) => {
+      tokens.set(value.resource, structuredClone(value));
+    },
+    remove: async (resource) => {
+      tokens.delete(resource);
+    }
+  };
+};
+var createMcpOAuthProvider = (options) => {
+  const now = options.now ?? Date.now;
+  let discovery;
+  const ensureDiscovery = async (metadataUrl) => discovery ??= await discoverMcpAuthorization({
+    endpoint: options.endpoint,
+    fetch: options.fetch,
+    resourceMetadataUrl: metadataUrl,
+    maxMetadataBytes: options.maxMetadataBytes
+  });
+  const refresh = async (tokens) => {
+    if (!tokens.refreshToken)
+      return false;
+    const found = await ensureDiscovery();
+    const params = new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: tokens.refreshToken,
+      client_id: options.clientId,
+      resource: found.resource.resource
+    });
+    if (tokens.scopes.length)
+      params.set("scope", tokens.scopes.join(" "));
+    const proof = await options.createDpopProof?.({
+      method: "POST",
+      url: found.authorizationServer.token_endpoint
+    });
+    const next = await tokenRequest({
+      endpoint: found.authorizationServer.token_endpoint,
+      fetch: options.fetch,
+      params,
+      dpopProof: proof,
+      now: now(),
+      resource: found.resource.resource
+    });
+    await options.store.save({
+      ...next,
+      refreshToken: next.refreshToken ?? tokens.refreshToken
+    });
+    return true;
+  };
+  return {
+    headers: async ({ method, url }) => {
+      let tokens = await options.store.load(options.endpoint);
+      if (!tokens)
+        return {};
+      if (tokens.expiresAt !== undefined && tokens.expiresAt <= now() + 5000) {
+        if (!await refresh(tokens))
+          return {};
+        tokens = await options.store.load(options.endpoint);
+        if (!tokens)
+          return {};
+      }
+      const headers = {
+        authorization: `${tokens.tokenType} ${tokens.accessToken}`
+      };
+      const proof = await options.createDpopProof?.({
+        accessToken: tokens.accessToken,
+        method,
+        url
+      });
+      if (proof)
+        headers.dpop = proof;
+      return headers;
+    },
+    onUnauthorized: async ({ response }) => {
+      const challenge = parseMcpAuthorizationChallenge(response.headers.get("www-authenticate"));
+      const found = await ensureDiscovery(challenge?.resourceMetadataUrl);
+      const existing = await options.store.load(found.resource.resource);
+      if (existing?.refreshToken && await refresh(existing))
+        return true;
+      const scopes = [
+        ...new Set([...options.scopes ?? [], ...challenge?.scopes ?? []])
+      ];
+      const request = await createMcpAuthorizationRequest({
+        discovery: found,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        scopes
+      });
+      const result = await options.onAuthorize({
+        authorizationUrl: request.authorizationUrl,
+        state: request.state,
+        scopes,
+        resource: found.resource.resource
+      });
+      if (result.state !== request.state)
+        throw new Error("OAuth state mismatch");
+      const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: result.code,
+        client_id: options.clientId,
+        redirect_uri: options.redirectUri,
+        code_verifier: request.codeVerifier,
+        resource: found.resource.resource
+      });
+      const proof = await options.createDpopProof?.({
+        method: "POST",
+        url: found.authorizationServer.token_endpoint
+      });
+      const tokens = await tokenRequest({
+        endpoint: found.authorizationServer.token_endpoint,
+        fetch: options.fetch,
+        params,
+        dpopProof: proof,
+        now: now(),
+        resource: found.resource.resource
+      });
+      await options.store.save(tokens);
+      return true;
+    }
+  };
+};
 // node_modules/@absolutejs/agency/dist/authzen.js
 var createCoazActionInput = ({
   actor,
@@ -466,6 +764,7 @@ var toolsList = async (config, caller, scopes, id, params) => {
   const tools = await config.tools({ caller, meta: {} });
   const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes) && agencyAllows(config, tool, scopes)).map(([name, tool]) => ({
     annotations: tool.annotations,
+    ...tool.coaz === undefined ? {} : { coaz: tool.coaz },
     description: tool.description,
     inputSchema: tool.inputSchema,
     name,
@@ -1257,17 +1556,22 @@ export {
   verifyBearer,
   publicMcpTask,
   protectedResourceMetadata,
+  parseMcpAuthorizationChallenge,
   metadataPathFor,
   mcpServer,
   mcpPostgresSchemaSql,
   feedbackTools,
   dispatchMcp,
+  discoverMcpAuthorization,
   createSessionRegistry,
   createPostgresMcpTaskStore,
   createPostgresMcpSessionStore,
   createMemoryMcpTaskStore,
+  createMemoryMcpOAuthTokenStore,
+  createMcpOAuthProvider,
   createMcpHandler,
   createMcpClient,
+  createMcpAuthorizationRequest,
   McpClientError,
   FEEDBACK_INSTRUCTIONS
 };

package/dist/manifest.js

@@ -5916,6 +5916,14 @@ var serializedTool = Type.Object({
 });
 var manifestSchema = Type.Object({
   contract: Type.Union([Type.Literal(1), Type.Literal(2)]),
+  discovery: Type.Optional(Type.Object({
+    audiences: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    certificationUrl: Type.Optional(Type.String()),
+    intents: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    keywords: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    protocols: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    url: Type.Optional(Type.String())
+  })),
   identity: Type.Object({
     accent: Type.Optional(Type.String({ pattern: "^#[0-9a-fA-F]{3,8}$" })),
     category: Type.String({ minLength: 1 }),

package/dist/src/client.d.ts

@@ -1,4 +1,5 @@
 import type { McpElicitationRequest, McpElicitResult, McpToolAnnotations, McpToolResult } from "./types";
+import type { McpAuthorizationProvider } from "./oauth";
 export declare class McpClientError extends Error {
     readonly code: number | undefined;
     readonly status: number | undefined;
@@ -8,6 +9,9 @@ export declare class McpClientError extends Error {
     });
 }
 export type McpClientOptions = {
+    /** Dynamic OAuth/DPoP provider. It may answer a 401 by completing discovery,
+     *  incremental authorization, or refresh; the request is retried once. */
+    authorization?: McpAuthorizationProvider;
     clientInfo?: {
         name: string;
         version: string;
@@ -30,6 +34,7 @@ export type McpClientOptions = {
 };
 export type McpRemoteTool = {
     annotations?: McpToolAnnotations;
+    coaz?: boolean;
     description?: string;
     inputSchema?: Record<string, unknown>;
     name: string;

package/dist/src/index.d.ts

@@ -32,6 +32,7 @@
  */
 export { verifyBearer, type BearerResult, type BearerVerifier, type VerifiedJwt, type VerifyBearerConfig, } from "./auth";
 export { createMcpClient, McpClientError, type McpClient, type McpClientOptions, type McpInitializeResult, type McpRemoteTool, } from "./client";
+export * from "./oauth";
 export { dispatchMcp, type McpDispatchContext } from "./dispatch";
 export { FEEDBACK_INSTRUCTIONS, feedbackTools, type McpFeedbackRating, type McpFeedbackReport, type McpFeedbackStore, type McpProblemReport, } from "./feedback";
 export { createMcpHandler } from "./handler";

package/dist/src/oauth.d.ts

@@ -0,0 +1,98 @@
+export type McpProtectedResourceMetadata = {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported?: string[];
+    bearer_methods_supported?: string[];
+    resource_name?: string;
+    resource_documentation?: string;
+};
+export type McpAuthorizationServerMetadata = {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    scopes_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    dpop_signing_alg_values_supported?: string[];
+    client_id_metadata_document_supported?: boolean;
+};
+export type McpOAuthTokens = {
+    accessToken: string;
+    tokenType: "Bearer" | "DPoP";
+    expiresAt?: number;
+    refreshToken?: string;
+    scopes: string[];
+    resource: string;
+};
+export type McpOAuthTokenStore = {
+    load(resource: string): Promise<McpOAuthTokens | undefined>;
+    save(tokens: McpOAuthTokens): Promise<void>;
+    remove(resource: string): Promise<void>;
+};
+export type McpAuthorizationChallenge = {
+    scheme: string;
+    resourceMetadataUrl?: string;
+    scopes: string[];
+    error?: string;
+};
+export type McpOAuthDiscovery = {
+    resource: McpProtectedResourceMetadata;
+    authorizationServer: McpAuthorizationServerMetadata;
+    resourceMetadataUrl: string;
+};
+export type McpAuthorizationProvider = {
+    headers(context: {
+        method: string;
+        url: string;
+    }): Promise<Record<string, string>> | Record<string, string>;
+    onUnauthorized?(context: {
+        method: string;
+        response: Response;
+        url: string;
+    }): Promise<boolean> | boolean;
+};
+export type McpOAuthInteractiveRequest = {
+    authorizationUrl: string;
+    state: string;
+    scopes: readonly string[];
+    resource: string;
+};
+export type McpOAuthOptions = {
+    clientId: string;
+    redirectUri: string;
+    store: McpOAuthTokenStore;
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    onAuthorize(request: McpOAuthInteractiveRequest): Promise<{
+        code: string;
+        state: string;
+    }>;
+    scopes?: string[];
+    createDpopProof?: (input: {
+        accessToken?: string;
+        method: string;
+        url: string;
+    }) => Promise<string>;
+    now?: () => number;
+    maxMetadataBytes?: number;
+};
+export declare const parseMcpAuthorizationChallenge: (value: string | null) => McpAuthorizationChallenge | undefined;
+export declare const discoverMcpAuthorization: ({ endpoint, fetch: fetcher, resourceMetadataUrl, maxMetadataBytes, }: {
+    endpoint: string;
+    fetch: McpOAuthOptions["fetch"];
+    resourceMetadataUrl?: string;
+    maxMetadataBytes?: number;
+}) => Promise<McpOAuthDiscovery>;
+export declare const createMcpAuthorizationRequest: ({ discovery, clientId, redirectUri, scopes, }: {
+    discovery: McpOAuthDiscovery;
+    clientId: string;
+    redirectUri: string;
+    scopes: readonly string[];
+}) => Promise<{
+    authorizationUrl: string;
+    codeVerifier: string;
+    state: string;
+}>;
+export declare const createMemoryMcpOAuthTokenStore: () => McpOAuthTokenStore;
+export declare const createMcpOAuthProvider: (options: McpOAuthOptions & {
+    endpoint: string;
+}) => McpAuthorizationProvider;

package/dist/src/types.d.ts

@@ -110,6 +110,9 @@ export type McpToolCallContext = {
 /** One callable tool. `inputSchema` is a JSON Schema object. */
 export type McpTool = {
     annotations?: McpToolAnnotations;
+    /** OpenID AuthZEN COAZ opt-in marker. When true, inputSchema MUST carry an
+     *  `x-coaz-mapping`; hosts should evaluate it before invoking the handler. */
+    coaz?: boolean;
     /** Enforceable semantic effects from manifest contract 2. A tool carrying
      *  this is hidden unless the server configures `agency`. */
     authorization?: ToolAuthorization;

package/package.json

@@ -11,8 +11,8 @@
     "elysia": ">=1.1.0"
   },
   "dependencies": {
-    "@absolutejs/agency": "^0.3.0",
-    "@absolutejs/manifest": "^0.2.0",
+    "@absolutejs/agency": "^0.4.0",
+    "@absolutejs/manifest": "^0.3.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "license": "BUSL-1.1",
@@ -58,5 +58,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.7.0"
+  "version": "0.9.0"
 }