@haikit/mcp 0.32.0 → 0.34.0

package/dist/transports.d.ts

@@ -1,15 +1,29 @@
-import { type StreamableHTTPClientTransportOptions, type Transport } from "@modelcontextprotocol/client";
+import { type AuthProvider, type FetchLike, type StreamableHTTPClientTransportOptions, type Transport } from "@modelcontextprotocol/client";
 import { type StdioServerParameters } from "@modelcontextprotocol/client/stdio";
 export interface HttpOptions extends StreamableHTTPClientTransportOptions {
     /** Sent on every request, over any of the same name in `requestInit.headers`. */
     headers?: Record<string, string>;
 }
+/** What `mcpServer({ auth })` needs to know of a transport `http()` made. */
+export interface HttpMade {
+    /** It was given an `authProvider` of its own. */
+    authProvider: boolean;
+    /** It sends an `Authorization` header of its own. */
+    authorization: boolean;
+    /** The server's URL: the protected resource an `oauth()` server's tokens are for. */
+    url: URL;
+    /** Its `fetch`, which an `oauth()` server's requests to the authorization server go through too. */
+    fetch: FetchLike | undefined;
+}
+/** The factories `http()` made: only these can carry each user's credential. */
+export declare const madeByHttp: WeakMap<object, HttpMade>;
 /**
  * A server at `url`, over Streamable HTTP. Everything but `headers` is the
  * SDK's own `StreamableHTTPClientTransportOptions`, such as an `authProvider`.
- * The URL is checked now, so a bad one fails at startup.
+ * The URL is checked now, so a bad one fails at startup. For a server with
+ * `auth`, each user's connection is given that user's `authProvider`.
  */
-export declare function http(url: string | URL, options?: HttpOptions): () => Transport;
+export declare function http(url: string | URL, options?: HttpOptions): (authProvider?: AuthProvider) => Transport;
 /**
  * A server this process starts, and talks to over its stdin and stdout. Each
  * connection starts a new child; `close()` stops it. Unless `env` is given,

package/dist/transports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,oCAAoC,EAAE,KAAK,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACxI,OAAO,EAAwB,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEtG,MAAM,WAAW,WAAY,SAAQ,oCAAoC;IACvE,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,SAAS,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,SAAS,CAEpE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,oCAAoC,EACzC,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAwB,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEtG,MAAM,WAAW,WAAY,SAAQ,oCAAoC;IACvE,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,GAAG,EAAE,GAAG,CAAC;IACT,oGAAoG;IACpG,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;CAC9B;AAED,gFAAgF;AAChF,eAAO,MAAM,UAAU,2BAAkC,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,WAAgB,GAAG,CAAC,YAAY,CAAC,EAAE,YAAY,KAAK,SAAS,CAiB7G;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,SAAS,CAEpE"}

package/dist/transports.js

@@ -1,9 +1,12 @@
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+/** The factories `http()` made: only these can carry each user's credential. */
+export const madeByHttp = new WeakMap();
 /**
  * A server at `url`, over Streamable HTTP. Everything but `headers` is the
  * SDK's own `StreamableHTTPClientTransportOptions`, such as an `authProvider`.
- * The URL is checked now, so a bad one fails at startup.
+ * The URL is checked now, so a bad one fails at startup. For a server with
+ * `auth`, each user's connection is given that user's `authProvider`.
  */
 export function http(url, options = {}) {
     const target = new URL(url);
@@ -14,7 +17,14 @@ export function http(url, options = {}) {
             merged.set(name, value);
         rest.requestInit = { ...rest.requestInit, headers: merged };
     }
-    return () => new StreamableHTTPClientTransport(target, rest);
+    const make = (authProvider) => new StreamableHTTPClientTransport(target, authProvider ? { ...rest, authProvider } : rest);
+    madeByHttp.set(make, {
+        authProvider: rest.authProvider !== undefined,
+        authorization: new Headers(rest.requestInit?.headers).has("authorization"),
+        url: target,
+        fetch: rest.fetch,
+    });
+    return make;
 }
 /**
  * A server this process starts, and talks to over its stdin and stdout. Each

package/dist/transports.js.map

@@ -1 +1 @@
-{"version":3,"file":"transports.js","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAA6D,MAAM,8BAA8B,CAAC;AACxI,OAAO,EAAE,oBAAoB,EAA8B,MAAM,oCAAoC,CAAC;AAOtG;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,GAAiB,EAAE,UAAuB,EAAE;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACrC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACtD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7E,IAAI,CAAC,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,EAAE,CAAC,IAAI,6BAA6B,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,MAA6B;IACjD,OAAO,GAAG,EAAE,CAAC,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"transports.js","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,GAK9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,oBAAoB,EAA8B,MAAM,oCAAoC,CAAC;AAmBtG,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,OAAO,EAAoB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,GAAiB,EAAE,UAAuB,EAAE;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACrC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACtD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7E,IAAI,CAAC,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC9D,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,YAA2B,EAAE,EAAE,CAC3C,IAAI,6BAA6B,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7F,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE;QACnB,YAAY,EAAE,IAAI,CAAC,YAAY,KAAK,SAAS;QAC7C,aAAa,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC;QAC1E,GAAG,EAAE,MAAM;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,MAA6B;IACjD,OAAO,GAAG,EAAE,CAAC,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/mcp",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Call MCP servers' tools from inside your haikit tools. The model never sees an MCP tool: your tool decides what it hears and what the browser shows. Imports only @haikit/core.",
   "keywords": [
     "haikit",
@@ -20,6 +20,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "default": "./dist/postgres.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -34,7 +38,7 @@
     "prepack": "npm --prefix ../.. run build"
   },
   "dependencies": {
-    "@haikit/core": "0.32.0",
+    "@haikit/core": "0.34.0",
     "@modelcontextprotocol/client": "^2.4.0",
     "@types/node": ">=22"
   },

package/src/auth.ts

@@ -0,0 +1,466 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AuthProvider, FetchLike, OAuthClientProvider } from "@modelcontextprotocol/client";
+import { LookupFailed, Lookup, NeedsAuth, type Credential } from "./credential.js";
+import { OAuthServer, isSecure, type OAuthCore, type OAuthServerOptions } from "./oauth.js";
+import { routes } from "./routes.js";
+import { SECRET_BYTES, Sealer } from "./seal.js";
+import { STORE_METHODS, type CredentialStore } from "./store.js";
+
+export { LookupFailed, Mismatch, NeedsAuth, type Credential } from "./credential.js";
+export type { OAuthServerOptions } from "./oauth.js";
+
+export interface McpAuthOptions {
+  /**
+   * Who a conversation belongs to: the user a call made in it runs as. With
+   * @haikit/auth, `(id) => auth.ownerOf(id)`. `null` for no one.
+   */
+  userOf(conversationId: string): string | null | Promise<string | null>;
+  /**
+   * Where each user's OAuth credentials are kept, sealed:
+   * `memoryCredentialStore()`, or `pgCredentialStore(db)` from
+   * `@haikit/mcp/postgres`. With `secret` and `redirectUri`, for `oauth()`.
+   */
+  store?: CredentialStore;
+  /**
+   * Seals every credential at rest. Several: the first seals, and every one
+   * opens, so a secret can be rotated out. Each at least 32 bytes.
+   */
+  secret?: string | string[];
+  /**
+   * Where an authorization server sends the browser back, exactly as
+   * registered with it: its path is the callback route. https, except on
+   * localhost.
+   */
+  redirectUri?: string;
+  /**
+   * The signed-in user a request to the routes comes from, or `null`. With
+   * @haikit/auth, `async (req) => (await auth.user(req))?.id ?? null`. For
+   * `handler()`.
+   */
+  requestUser?(req: IncomingMessage): string | null | Promise<string | null>;
+  /**
+   * A user has connected an account, at the callback route. With the
+   * conversation the connect link was for, if they own it. What it throws is
+   * logged: the user is connected all the same.
+   */
+  onConnected?(connected: McpConnected): void | Promise<void>;
+  /** Where `handler()`'s routes are, and the connect links point. Default `"/mcp"`. */
+  basePath?: string;
+  /** The app's name, which an authorization server shows when the user connects. Default: the redirect URI's host. */
+  clientName?: string;
+}
+
+/** What `onConnected` is told. */
+export interface McpConnected {
+  userId: string;
+  server: string;
+  /** The conversation the connect link was for: only one the user owns. */
+  conversationId?: string;
+}
+
+/** A server a user has connected an account for, from `connections()`. */
+export interface McpAccount {
+  /** The server's `name`. */
+  name: string;
+  /** The scope granted, or asked for when the authorization server didn't say. */
+  scope: string | null;
+  /** When the user connected, epoch ms. */
+  connectedAt: number;
+}
+
+/** Makes the `auth` of servers whose calls are made as each user. */
+export interface McpAuth {
+  /**
+   * Each user's own token, which the app already has: `token(userId)` gives
+   * it, or `null` when the user has none. Sent as `Authorization: Bearer`.
+   */
+  bearer(token: (userId: string) => string | null | Promise<string | null>): McpServerAuth;
+  /**
+   * Each user connects their account through the connect route, and the
+   * store keeps their tokens. Needs `store`, `secret` and `redirectUri`.
+   */
+  oauth(options?: OAuthServerOptions): McpServerAuth;
+  /**
+   * One of the SDK's own providers, made for each user: `make(userId)` gives
+   * it, or `null` when the user has none. The app owns the whole provider:
+   * nothing is stored, and there's no connect route.
+   */
+  sdk(make: (userId: string) => AuthProvider | OAuthClientProvider | null | Promise<AuthProvider | OAuthClientProvider | null>): McpServerAuth;
+  /**
+   * The routes, under `basePath`: connect, the callback at the redirect URI's
+   * path, disconnect, the user's connections, and the client metadata
+   * document. Resolves false for anything else. Needs `requestUser`.
+   */
+  handler(): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+  /** The `oauth()` servers a user has connected an account for. */
+  connections(userId: string): Promise<McpAccount[]>;
+  /**
+   * Revokes a user's tokens for a server where its authorization server takes
+   * it, deletes them, and closes the user's connection; with no `server`, for
+   * every server they connected.
+   */
+  disconnect(userId: string, server?: string): Promise<void>;
+}
+
+/** How a server's calls are made as each user: made by an `McpAuth`, and given to `mcpServer({ auth })`. */
+export interface McpServerAuth {
+  readonly kind: "bearer" | "oauth" | "sdk";
+}
+
+/** What a server tells its `McpAuth` of itself. */
+export interface Attached {
+  name: string;
+  timeoutMs: number;
+  url: URL;
+  fetch: FetchLike | undefined;
+  forget(userId: string): Promise<void>;
+}
+
+/** A server's place on its `McpAuth`. */
+export interface Binding {
+  /** The user's credential, for a new connection of theirs. */
+  credential(userId: string): Credential;
+  /** The connect route's path, for an `oauth()` server: for this conversation, and asking for `scope`. */
+  readonly connect: ((conversationId: string | undefined, scope: string | undefined) => string) | null;
+  /** Frees the name, for a closed server. */
+  detach(): void;
+}
+
+/** What an `McpServerAuth` stands for. */
+export interface AuthConfig {
+  readonly kind: McpServerAuth["kind"];
+  userOf(conversationId: string): string | null | Promise<string | null>;
+  /** Takes the server's name on this `McpAuth`, or throws if another server has it: the name keys its users' credentials. */
+  attach(server: Attached): Binding;
+}
+
+const configs = new WeakMap<object, AuthConfig>();
+
+/** The config an `McpServerAuth` stands for, or undefined if `createMcpAuth` didn't make it. */
+export const configOf = (auth: unknown): AuthConfig | undefined =>
+  typeof auth === "object" && auth !== null ? configs.get(auth) : undefined;
+
+const BASE_PATH = /^(\/[A-Za-z0-9\-._~!$&'()*+,;=:@%]+)+$/;
+/** What `handler()` answers under `basePath` itself. */
+const ROUTES = ["connect", "disconnect", "connections", "client.json"];
+
+/**
+ * For servers whose calls are made as each user, with that user's own
+ * credential: `mcpServer({ auth: mcpAuth.oauth() })`.
+ */
+export function createMcpAuth(options: McpAuthOptions): McpAuth {
+  if (typeof options?.userOf !== "function") {
+    throw new TypeError("createMcpAuth: userOf must be a function, such as (id) => auth.ownerOf(id)");
+  }
+  for (const name of ["requestUser", "onConnected"] as const) {
+    if (options[name] !== undefined && typeof options[name] !== "function") throw new TypeError(`createMcpAuth: ${name} must be a function`);
+  }
+  const basePath = options.basePath ?? "/mcp";
+  if (typeof basePath !== "string" || !BASE_PATH.test(basePath)) {
+    throw new TypeError(`createMcpAuth: basePath must be a path such as "/mcp", with no trailing slash (got ${JSON.stringify(basePath)})`);
+  }
+  // a request's path is read as a URL, which takes out dot segments: one there would match no route
+  if (new URL(basePath, "http://localhost").pathname !== basePath) {
+    throw new TypeError(`createMcpAuth: basePath can't have a "." or ".." segment (got ${JSON.stringify(basePath)})`);
+  }
+  const core = oauthCore(options, basePath);
+
+  /** Every server attached, by name: its kind, and its OAuth if it has one. */
+  const servers = new Map<string, { forget(userId: string): Promise<void>; oauth: OAuthServer | null }>();
+  const userOf = (conversationId: string) => options.userOf(conversationId);
+
+  function make(kind: McpServerAuth["kind"], bind: (server: Attached) => Omit<Binding, "detach">): McpServerAuth {
+    const auth: McpServerAuth = Object.freeze({ kind });
+    configs.set(auth, {
+      kind,
+      userOf,
+      attach(server) {
+        if (servers.has(server.name)) throw new TypeError(`another server from the same createMcpAuth is named "${server.name}"`);
+        const bound = bind(server);
+        const entry = { forget: server.forget, oauth: bound instanceof OAuthBinding ? bound.oauth : null };
+        servers.set(server.name, entry);
+        return {
+          credential: (user) => bound.credential(user),
+          connect: bound.connect,
+          detach: () => {
+            if (servers.get(server.name) === entry) servers.delete(server.name);
+          },
+        };
+      },
+    });
+    return auth;
+  }
+
+  const needsStore = (what: string) => {
+    if (!core) throw new TypeError(`${what} needs createMcpAuth({ store, secret, redirectUri })`);
+    return core;
+  };
+
+  return Object.freeze({
+    bearer(token: (userId: string) => string | null | Promise<string | null>): McpServerAuth {
+      if (typeof token !== "function") {
+        throw new TypeError("bearer: token must be a function that takes a user id and returns their token, or null");
+      }
+      return make("bearer", (server) => ({
+        credential: (user: string) => new BearerCredential(token, user, server.timeoutMs),
+        connect: null,
+      }));
+    },
+
+    oauth(oauthOptions: OAuthServerOptions = {}): McpServerAuth {
+      const ready = needsStore("oauth()");
+      const checked = checkOAuth(oauthOptions);
+      return make("oauth", (server) => new OAuthBinding(new OAuthServer(ready, checked, server.name, server.url, server.fetch ?? fetch, server.timeoutMs, server.forget), basePath));
+    },
+
+    sdk(makeProvider: (userId: string) => ProviderOrNull | Promise<ProviderOrNull>): McpServerAuth {
+      if (typeof makeProvider !== "function") {
+        throw new TypeError("sdk: make must be a function that takes a user id and returns their AuthProvider, or null");
+      }
+      return make("sdk", (server) => ({
+        credential: (user: string) => new SdkCredential(makeProvider, user, server.timeoutMs),
+        connect: null,
+      }));
+    },
+
+    handler() {
+      const ready = needsStore("handler()");
+      if (!options.requestUser) throw new TypeError("handler() needs createMcpAuth's requestUser: its routes act for the user signed in");
+      const requestUser = options.requestUser;
+      return routes({
+        core: ready,
+        basePath,
+        requestUser: async (req) => nonEmpty(await requestUser(req)),
+        userOf: async (id) => nonEmpty(await options.userOf(id)),
+        onConnected: options.onConnected,
+        oauth: (name) => servers.get(name)?.oauth ?? undefined,
+        connections,
+        disconnect,
+      });
+    },
+
+    connections,
+    disconnect,
+  });
+
+  async function connections(userId: string): Promise<McpAccount[]> {
+    const ready = needsStore("connections()");
+    if (typeof userId !== "string" || userId === "") throw new TypeError("connections() needs a userId");
+    const accounts: McpAccount[] = [];
+    for (const name of await ready.store.list(userId)) {
+      const held = await servers.get(name)?.oauth?.read(userId);
+      if (held) accounts.push({ name, scope: held.kept.scope, connectedAt: held.kept.connectedAt });
+    }
+    return accounts;
+  }
+
+  async function disconnect(userId: string, server?: string): Promise<void> {
+    const ready = needsStore("disconnect()");
+    if (typeof userId !== "string" || userId === "") throw new TypeError("disconnect() needs a userId");
+    if (server !== undefined && (typeof server !== "string" || server === "")) throw new TypeError("disconnect(): server must be a server's name");
+    for (const name of server === undefined ? await ready.store.list(userId) : [server]) {
+      const oauth = servers.get(name)?.oauth;
+      if (oauth) await oauth.disconnect(userId);
+      // a server no longer configured: nothing to revoke with, or close
+      else await ready.store.delete(userId, name);
+    }
+  }
+}
+
+/** An `oauth()` server's place on its `McpAuth`. */
+class OAuthBinding {
+  constructor(
+    readonly oauth: OAuthServer,
+    private readonly basePath: string,
+  ) {}
+
+  credential(user: string): Credential {
+    return this.oauth.credential(user);
+  }
+
+  readonly connect = (conversationId: string | undefined, scope: string | undefined): string => {
+    const query = new URLSearchParams();
+    if (conversationId !== undefined) query.set("conversation", conversationId);
+    if (scope !== undefined) query.set("scope", scope);
+    const search = query.toString();
+    return `${this.basePath}/connect/${encodeURIComponent(this.oauth.name)}${search ? `?${search}` : ""}`;
+  };
+}
+
+/** What `oauth()` needs of `createMcpAuth`'s options, checked: null if none of it is given. */
+function oauthCore(options: McpAuthOptions, basePath: string): OAuthCore | null {
+  const { store, secret, redirectUri } = options;
+  if (store === undefined && secret === undefined && redirectUri === undefined) return null;
+  if (store === undefined || secret === undefined || redirectUri === undefined) {
+    throw new TypeError("createMcpAuth: store, secret and redirectUri go together: oauth() needs all three");
+  }
+  if (typeof store !== "object" || store === null || STORE_METHODS.some((m) => typeof store[m] !== "function")) {
+    throw new TypeError("createMcpAuth: store must be a CredentialStore, such as memoryCredentialStore()");
+  }
+  const secrets = [secret].flat();
+  if (!secrets.length || secrets.some((s) => typeof s !== "string")) throw new TypeError("createMcpAuth: secret must be a string, or a list of them");
+  if (secrets.some((s) => Buffer.byteLength(s) < SECRET_BYTES)) throw new TypeError(`createMcpAuth: each secret must be at least ${SECRET_BYTES} bytes`);
+  let callback: URL;
+  try {
+    callback = new URL(redirectUri);
+  } catch {
+    throw new TypeError("createMcpAuth: redirectUri must be a URL, such as https://app.example.com/mcp/callback");
+  }
+  if (!isSecure(callback)) throw new TypeError("createMcpAuth: redirectUri must be https, except on localhost");
+  if (callback.hash || callback.search) throw new TypeError("createMcpAuth: redirectUri can't have a query or a fragment");
+  const path = callback.pathname;
+  if (ROUTES.some((route) => path === `${basePath}/${route}` || path.startsWith(`${basePath}/${route}/`))) {
+    throw new TypeError(`createMcpAuth: redirectUri comes back to ${path}, a route handler() answers already`);
+  }
+  const clientName = options.clientName ?? callback.host;
+  if (typeof clientName !== "string" || clientName === "") throw new TypeError("createMcpAuth: clientName must be a non-empty string");
+  return {
+    store,
+    sealer: new Sealer(secrets),
+    redirectUri: callback.href,
+    clientMetadata: {
+      client_name: clientName,
+      redirect_uris: [callback.href],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    },
+    // the SDK refuses a client identified by a URL that isn't https: on localhost, it registers one
+    clientMetadataUrl: callback.protocol === "https:" ? new URL(`${basePath}/client.json`, callback).href : undefined,
+  };
+}
+
+function checkOAuth(options: OAuthServerOptions): OAuthServerOptions {
+  if (typeof options !== "object" || options === null) throw new TypeError("oauth: options must be an object");
+  const { issuer, scopes, client } = options;
+  if (issuer !== undefined) {
+    if (typeof issuer !== "string" || !URL.canParse(issuer)) throw new TypeError("oauth: issuer must be the authorization server's issuer URL");
+    if (!isSecure(issuer)) throw new TypeError("oauth: issuer must be https, except on localhost");
+  }
+  if (scopes !== undefined && (!Array.isArray(scopes) || scopes.some((s) => typeof s !== "string" || !/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(s)))) {
+    throw new TypeError("oauth: scopes must be a list of OAuth scopes, such as [\"repo\"], each without spaces");
+  }
+  if (client !== undefined) {
+    if (typeof client?.id !== "string" || client.id === "" || (client.secret !== undefined && typeof client.secret !== "string")) {
+      throw new TypeError("oauth: client must be { id, secret? }, as registered with the authorization server");
+    }
+    if (issuer === undefined) throw new TypeError("oauth: a client needs the issuer it was registered with");
+  }
+  return Object.freeze({ ...options, ...(scopes ? { scopes: [...scopes] } : {}), ...(client ? { client: { ...client } } : {}) });
+}
+
+type ProviderOrNull = AuthProvider | OAuthClientProvider | null;
+
+const nonEmpty = (value: unknown): string | null => (typeof value === "string" && value !== "" ? value : null);
+
+/** A token from `bearer`'s function, kept until a lookup on a 401 finds another, or none. */
+export class BearerCredential implements Credential {
+  private token: string | null = null;
+  /** The lookup on its way, which every caller shares: only it sets `token`. */
+  private looking: Promise<string | null> | null = null;
+  /** Bounds `read`: a lookup that never answers would hold up every call after it. */
+  private readonly lookups: Lookup;
+
+  constructor(
+    private readonly read: (userId: string) => string | null | Promise<string | null>,
+    private readonly user: string,
+    /** How long `read` may take. */
+    timeoutMs: number,
+  ) {
+    this.lookups = new Lookup(timeoutMs, "token");
+  }
+
+  async ensure(): Promise<boolean> {
+    if (this.token === null) await this.look();
+    if (this.token === null) throw new NeedsAuth("connect");
+    return false;
+  }
+
+  close(): void {
+    this.lookups.stop();
+  }
+
+  // The transport asks for the token before every request, and on a 401
+  // calls onUnauthorized, then tries once more with what it finds.
+  readonly provider: AuthProvider = {
+    // A request is never sent without the user's token: the transport would
+    // send it with no Authorization at all. Gone since its call began, as
+    // when another call's 401 found none, it stops the request here.
+    token: async () => {
+      if (this.token === null) throw new NeedsAuth("reconnect");
+      return this.token;
+    },
+    onUnauthorized: async () => {
+      // A token the server still refuses gets its 401 on the retry, and is
+      // kept: the next 401 looks again. Forgetting it would throw away a
+      // newer one that another call's 401 found meanwhile.
+      if ((await this.look()) === null) throw new NeedsAuth("reconnect");
+    },
+  };
+
+  /** One lookup at a time, for first calls and 401s that come together, so none overwrites another's token. */
+  private look(): Promise<string | null> {
+    this.looking ??= this.lookup()
+      .then((token) => (this.token = token))
+      .finally(() => {
+        this.looking = null;
+      });
+    return this.looking;
+  }
+
+  private async lookup(): Promise<string | null> {
+    let token: unknown;
+    try {
+      token = await this.lookups.run(() => this.read(this.user));
+    } catch (err) {
+      throw new LookupFailed(err);
+    }
+    return typeof token === "string" && token !== "" ? token : null;
+  }
+}
+
+/** A provider from `sdk()`'s function, made once for each connection: the app's provider does the rest. */
+class SdkCredential implements Credential {
+  private made: AuthProvider | OAuthClientProvider | null = null;
+  private looking: Promise<void> | null = null;
+  private readonly lookups: Lookup;
+
+  constructor(
+    private readonly make: (userId: string) => ProviderOrNull | Promise<ProviderOrNull>,
+    private readonly user: string,
+    timeoutMs: number,
+  ) {
+    this.lookups = new Lookup(timeoutMs, "provider");
+  }
+
+  async ensure(): Promise<boolean> {
+    if (this.made === null) {
+      this.looking ??= this.lookups
+        .run(() => this.make(this.user))
+        .then(
+          (made) => {
+            this.made = typeof made === "object" && made !== null ? made : null;
+          },
+          (err) => {
+            throw new LookupFailed(err);
+          },
+        )
+        .finally(() => {
+          this.looking = null;
+        });
+      await this.looking;
+    }
+    if (this.made === null) throw new NeedsAuth("connect");
+    return false;
+  }
+
+  close(): void {
+    this.lookups.stop();
+  }
+
+  get provider(): AuthProvider | OAuthClientProvider {
+    // never asked for before ensure() has made it: a connection dials only after
+    if (this.made === null) throw new NeedsAuth("connect");
+    return this.made;
+  }
+}

package/src/credential.ts

@@ -0,0 +1,78 @@
+import type { AuthProvider, OAuthClientProvider } from "@modelcontextprotocol/client";
+
+/**
+ * The user has no credential, or the server refused theirs: thrown inside a
+ * connection, where the transport passes it on unchanged, and made an
+ * `McpError` with reason `auth`.
+ */
+export class NeedsAuth extends Error {
+  readonly name = "NeedsAuth";
+  constructor(readonly kind: "connect" | "reconnect") {
+    super(kind === "connect" ? "the user has no credential" : "the server refused the user's credential");
+  }
+}
+
+/** The app's lookup of a credential failed, or a refresh couldn't be made: made an `McpError` with reason `connection`. */
+export class LookupFailed extends Error {
+  readonly name = "LookupFailed";
+  constructor(cause: unknown) {
+    super("the user's credential could not be looked up", { cause });
+  }
+}
+
+/**
+ * The server names another authorization server than the one its `issuer`
+ * pins, or than the one that issued a credential: made an `McpError` with
+ * reason `protocol`. The pin decides, not the user, so it's never `auth`.
+ */
+export class Mismatch extends Error {
+  readonly name = "Mismatch";
+}
+
+/** One user's credential for one server, and the `AuthProvider` that sends it. */
+export interface Credential {
+  /**
+   * Before a connection or call: finds the credential, or throws
+   * `NeedsAuth("connect")`, so nothing is sent without one. True when it's
+   * now another account than before: the connection made with the old one
+   * is made again.
+   */
+  ensure(): Promise<boolean>;
+  /** For a connection being closed: stops a lookup on its way, and its timer. */
+  close(): void;
+  /** What each connection's transport is given, read as it's made, once `ensure()` has found the credential. */
+  readonly provider: AuthProvider | OAuthClientProvider;
+}
+
+/**
+ * A lookup that takes at most `ms`, and that `stop()` ends at once: one that
+ * never answered would hold up every call after it, and its timer would keep
+ * the process going.
+ */
+export class Lookup {
+  private stopping: (() => void) | null = null;
+
+  constructor(
+    private readonly ms: number,
+    /** Names what's looked up, in the errors. */
+    private readonly what: string,
+  ) {}
+
+  async run<T>(look: () => T | Promise<T>): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const cut = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`no ${this.what} within ${this.ms} ms`)), this.ms);
+      this.stopping = () => reject(new Error(`closed while the ${this.what} was being looked up`));
+    });
+    try {
+      return await Promise.race([Promise.resolve().then(look), cut]);
+    } finally {
+      clearTimeout(timer);
+      this.stopping = null;
+    }
+  }
+
+  stop(): void {
+    this.stopping?.();
+  }
+}