@absolutejs/mcp 0.6.0 → 0.8.0

package/README.md

@@ -262,6 +262,32 @@ elicitation is safe behind a load balancer with **no sticky routing** — there
 a test for exactly that: instance A asks, the answer lands on B, the bus carries
 it back, and A's call finishes.
 
+AbsoluteJS already ships both production transports. PostgreSQL is the default;
+Redis is an optional at-most-once fan-out optimization:
+
+```ts
+import { createPostgresChannelBus } from "@absolutejs/sync-bus-pg";
+import type { McpElicitAnswer } from "@absolutejs/mcp";
+
+const bus = createPostgresChannelBus<McpElicitAnswer>({
+  sql,
+  channel: "absolutejs_mcp_elicitation",
+  spill: "always",
+});
+
+const config = {
+  // ...
+  elicitation: {
+    enabled: true,
+    store: createPostgresMcpSessionStore({ sql }),
+    bus,
+  },
+};
+```
+
+The channel is only coordination: durable jobs and side effects belong in
+`@absolutejs/queue` / `@absolutejs/execution`, not Redis pub/sub or NOTIFY.
+
 Consuming a server that elicits? Pass `onElicit` to `createMcpClient` — that is
 what declares the capability, and what the package uses to answer. Omit it and
 servers are told you cannot ask anyone.
@@ -283,6 +309,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;
@@ -285,6 +305,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,
@@ -786,14 +1083,14 @@ var resourcesRead = async (config, caller, id, params) => {
     ]
   });
 };
-var elicitAnswer = (message, context) => {
+var elicitAnswer = async (message, context) => {
   const requestId = typeof message.id === "string" ? message.id : null;
   if (!requestId || !context.sessions)
     return notificationAck();
   const result = isRecord(message.result) ? message.result : null;
   const action = result?.action;
   const answer = action === "accept" && isRecord(result?.content) ? { action: "accept", content: result.content } : action === "decline" ? { action: "decline" } : { action: "cancel" };
-  context.sessions.resolveElicit({
+  await context.sessions.resolveElicit({
     requestId,
     result: answer,
     sessionId: context.sessionId ?? null
@@ -984,6 +1281,7 @@ var createSessionRegistry = (options) => {
   const elicitTimeoutMs = options?.elicitTimeoutMs ?? DEFAULT_ELICIT_TIMEOUT_MS;
   const store = options?.store ?? createMemoryStore(ttlMs);
   const pending = new Map;
+  let unsubscribe;
   const resolveLocal = (answer) => {
     const waiting = pending.get(answer.requestId);
     if (!waiting)
@@ -993,19 +1291,39 @@ var createSessionRegistry = (options) => {
     waiting.resolve(answer.result);
     return true;
   };
-  options?.bus?.subscribe((answer) => {
+  const ready = options?.bus ? Promise.resolve(options.bus.subscribe((answer) => {
     resolveLocal(answer);
-  });
+  })).then((stop) => {
+    unsubscribe = stop;
+  }) : Promise.resolve();
   return {
-    create: async (canElicit) => await store.create({ canElicit }),
+    ready,
+    close: async () => {
+      await ready;
+      await unsubscribe?.();
+      pending.forEach(({ resolve, timer }) => {
+        clearTimeout(timer);
+        resolve({ action: "cancel" });
+      });
+      pending.clear();
+    },
+    create: async (canElicit) => {
+      await ready;
+      return await store.create({ canElicit });
+    },
     drop: async (id) => {
+      await ready;
       await store.drop(id);
     },
-    get: async (id) => id ? await store.get(id) : null,
-    resolveElicit: (answer) => {
+    get: async (id) => {
+      await ready;
+      return id ? await store.get(id) : null;
+    },
+    resolveElicit: async (answer) => {
+      await ready;
       if (resolveLocal(answer))
         return true;
-      options?.bus?.publish(answer);
+      await options?.bus?.publish(answer);
       return false;
     },
     startElicit: (request) => {
@@ -1167,12 +1485,24 @@ var createPostgresMcpTaskStore = ({
   return {
     cancel: async (taskId) => {
       const updatedAt = now().toISOString();
-      await client.query(`UPDATE ${ns}.tasks SET status = 'cancelled', updated_at = $2::timestamptz, data = data || $3::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed')`, [taskId, updatedAt, JSON.stringify({ lastUpdatedAt: updatedAt, status: "cancelled" })]);
+      await client.query(`UPDATE ${ns}.tasks SET status = 'cancelled', updated_at = $2::timestamptz, data = data || $3::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed')`, [
+        taskId,
+        updatedAt,
+        JSON.stringify({ lastUpdatedAt: updatedAt, status: "cancelled" })
+      ]);
     },
     get: async (taskId) => (await client.query(`SELECT data FROM ${ns}.tasks WHERE task_id = $1 AND (expires_at IS NULL OR expires_at > $2::timestamptz)`, [taskId, now().toISOString()])).rows[0]?.data ?? null,
     save: async (task) => {
       const expiresAt = task.ttlMs === null ? null : new Date(new Date(task.createdAt).getTime() + task.ttlMs).toISOString();
-      await client.query(`INSERT INTO ${ns}.tasks (task_id, authorization_key, status, created_at, updated_at, expires_at, data) VALUES ($1, $2, $3, $4::timestamptz, $5::timestamptz, $6::timestamptz, $7::jsonb) ON CONFLICT (task_id) DO NOTHING`, [task.taskId, task.authorizationKey, task.status, task.createdAt, task.lastUpdatedAt, expiresAt, JSON.stringify(task)]);
+      await client.query(`INSERT INTO ${ns}.tasks (task_id, authorization_key, status, created_at, updated_at, expires_at, data) VALUES ($1, $2, $3, $4::timestamptz, $5::timestamptz, $6::timestamptz, $7::jsonb) ON CONFLICT (task_id) DO NOTHING`, [
+        task.taskId,
+        task.authorizationKey,
+        task.status,
+        task.createdAt,
+        task.lastUpdatedAt,
+        expiresAt,
+        JSON.stringify(task)
+      ]);
     },
     update: async (taskId, update) => {
       const updatedAt = now().toISOString();
@@ -1195,15 +1525,26 @@ var createPostgresMcpSessionStore = ({
     create: async ({ canElicit }) => {
       const id = crypto.randomUUID();
       const current = now();
-      await client.query(`INSERT INTO ${ns}.sessions (session_id, can_elicit, created_at, last_seen_at, expires_at) VALUES ($1, $2, $3::timestamptz, $3::timestamptz, $4::timestamptz)`, [id, canElicit, current.toISOString(), new Date(current.getTime() + ttlMs).toISOString()]);
+      await client.query(`INSERT INTO ${ns}.sessions (session_id, can_elicit, created_at, last_seen_at, expires_at) VALUES ($1, $2, $3::timestamptz, $3::timestamptz, $4::timestamptz)`, [
+        id,
+        canElicit,
+        current.toISOString(),
+        new Date(current.getTime() + ttlMs).toISOString()
+      ]);
       return id;
     },
     drop: async (id) => {
-      await client.query(`DELETE FROM ${ns}.sessions WHERE session_id = $1`, [id]);
+      await client.query(`DELETE FROM ${ns}.sessions WHERE session_id = $1`, [
+        id
+      ]);
     },
     get: async (id) => {
       const current = now();
-      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit`, [id, current.toISOString(), new Date(current.getTime() + ttlMs).toISOString()]);
+      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit`, [
+        id,
+        current.toISOString(),
+        new Date(current.getTime() + ttlMs).toISOString()
+      ]);
       const row = result.rows[0];
       return row === undefined ? null : { canElicit: row.can_elicit };
     }
@@ -1213,17 +1554,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/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;

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/sessions.d.ts

@@ -6,6 +6,8 @@ export declare const createSessionRegistry: (options?: {
     store?: McpSessionStore;
     ttlMs?: number;
 }) => {
+    ready: Promise<void>;
+    close: () => Promise<void>;
     create: (canElicit: boolean) => Promise<string>;
     drop: (id: string) => Promise<void>;
     get: (id: string | null) => Promise<{
@@ -14,7 +16,7 @@ export declare const createSessionRegistry: (options?: {
     /** The client answered. If the call that asked is running HERE, resolve it.
      *  If not, put the answer on the bus so the instance that is waiting can —
      *  the answer must find the promise, and the promise cannot move. */
-    resolveElicit: (answer: McpElicitAnswer) => boolean;
+    resolveElicit: (answer: McpElicitAnswer) => Promise<boolean>;
     /** Register an outbound question. Returns the id to send it under and the
      *  promise that settles when the user answers — or when they never do. */
     startElicit: (request: McpElicitationRequest) => {

package/dist/src/types.d.ts

@@ -93,8 +93,8 @@ export type McpSessionStore = {
  *  routing. Omit it and you must run a single instance (or pin sessions). */
 export type McpElicitBus = {
     /** An answer nobody here was waiting for — someone else might be. */
-    publish: (answer: McpElicitAnswer) => void;
-    subscribe: (handler: (answer: McpElicitAnswer) => void) => void;
+    publish: (answer: McpElicitAnswer) => void | Promise<void>;
+    subscribe: (handler: (answer: McpElicitAnswer) => void) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
 };
 /** Passed to a tool handler as its second argument. Ignore it and nothing
  *  changes — every existing handler keeps working. */

package/package.json

@@ -58,5 +58,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.6.0"
+  "version": "0.8.0"
 }