@haikit/mcp 0.33.0 → 0.34.0

package/README.md

@@ -58,25 +58,64 @@ call runs as the conversation's owner, over a connection of their own:
 
 ```ts
 import { createMcpAuth } from "@haikit/mcp";
+import { pgCredentialStore } from "@haikit/mcp/postgres";
 
-const mcpAuth = createMcpAuth({ userOf: (id) => auth.ownerOf(id) }); // auth from @haikit/auth
+const mcpAuth = createMcpAuth({
+  userOf: (id) => auth.ownerOf(id), // auth from @haikit/auth
+  // for oauth(): where each user's tokens are kept, sealed, and who's signed in
+  store: pgCredentialStore(pool), // or memoryCredentialStore()
+  secret: process.env.MCP_SECRET!, // 32 bytes or more; a list to rotate
+  redirectUri: "https://app.example.com/mcp/callback",
+  requestUser: async (req) => (await auth.user(req))?.id ?? null,
+  onConnected: ({ userId, server, conversationId }) => { /* wake the conversation */ },
+});
+
+// a token the app already has for each user, or null
 const tracker = mcpServer({
   name: "tracker",
   transport: http("https://mcp.tracker.example/mcp"),
-  auth: mcpAuth.bearer((userId) => keys.find(userId)), // their token, or null
+  auth: mcpAuth.bearer((userId) => keys.find(userId)),
+});
+
+// each user connects their own account, with the server's authorization server
+const linear = mcpServer({
+  name: "linear",
+  transport: http("https://mcp.linear.example/mcp"),
+  auth: mcpAuth.oauth({ issuer: "https://linear.example" }), // pin a third party's
+});
+
+// the connect, callback and disconnect routes, beside your own
+const mcpRoutes = mcpAuth.handler();
+createServer(async (req, res) => {
+  if (await mcpRoutes(req, res)) return;
+  // ...
 });
 ```
 
 A call with no one to run as is refused with reason `user`, and one for a user
-with no token with reason `auth`, before anything is sent: it never falls
-back to the app's identity. `err.auth.kind` says what the user must do:
-`connect`, `reconnect`, or grant more `scope`. A job outside any conversation
-passes `{ userId }`.
+with no credential with reason `auth`, before anything is sent: it never
+falls back to the app's identity. `err.auth.kind` says what the user must
+do: `connect`, `reconnect`, or grant more `scope`. For an `oauth()` server,
+`err.auth.connect` is the app's link for it, such as
+`/mcp/connect/linear?conversation=c_123`, to show the user in a surface,
+never to give the model. A job outside any conversation passes `{ userId }`.
+
+With `oauth()`, the connect route sends the user to the authorization server
+with PKCE, and the callback stores their tokens sealed with `secret`, bound
+to the user and the server. A 401 refreshes them once, however many calls
+get one. Across app processes sharing the store, one at a time takes the
+store's refresh lease and spends the refresh token, and the others use what
+it stores. Each call reads the store first, so a refresh, a connect or a
+disconnect in another process is seen on the next call. `connections(userId)` lists what a user connected, and
+`disconnect(userId, server?)` revokes and deletes.
+`mcpAuth.sdk(make)` takes one of the SDK's own providers for each user
+instead.
 
 `McpTool` isn't a HaiKIT `Tool`, so it can't be passed to
 `createHai({ tools })`: `npm run typetest` checks that.
 
-Imports only `@haikit/core`, never `@haikit/server`. Built on
+Imports only `@haikit/core`, never `@haikit/server`. `@haikit/mcp/postgres`
+takes any driver with `query(text, params)`, such as a `pg.Pool`. Built on
 [`@modelcontextprotocol/client`](https://www.npmjs.com/package/@modelcontextprotocol/client),
 the official TypeScript SDK's client.
 

package/dist/auth.d.ts

@@ -1,10 +1,65 @@
-import type { AuthProvider } from "@modelcontextprotocol/client";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AuthProvider, FetchLike, OAuthClientProvider } from "@modelcontextprotocol/client";
+import { type Credential } from "./credential.js";
+import { type OAuthServerOptions } from "./oauth.js";
+import { 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 {
@@ -13,64 +68,80 @@ export interface McpAuth {
      * 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";
+    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: "bearer";
+    readonly kind: McpServerAuth["kind"];
     userOf(conversationId: string): string | null | Promise<string | null>;
-    token(userId: string): string | null | Promise<string | null>;
-    /** Server names in use with this `McpAuth`: each is a key for its users' credentials. */
-    readonly names: Set<string>;
+    /** 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;
 }
 /** The config an `McpServerAuth` stands for, or undefined if `createMcpAuth` didn't make it. */
 export declare const configOf: (auth: unknown) => AuthConfig | undefined;
 /**
  * For servers whose calls are made as each user, with that user's own
- * credential: `mcpServer({ auth: mcpAuth.bearer(token) })`.
+ * credential: `mcpServer({ auth: mcpAuth.oauth() })`.
  */
 export declare function createMcpAuth(options: McpAuthOptions): McpAuth;
-/**
- * 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 declare class NeedsAuth extends Error {
-    readonly kind: "connect" | "reconnect";
-    readonly name = "NeedsAuth";
-    constructor(kind: "connect" | "reconnect");
-}
-/** The app's lookup of a credential failed: made an `McpError` with reason `connection`. */
-export declare class LookupFailed extends Error {
-    readonly name = "LookupFailed";
-    constructor(cause: unknown);
-}
-/** 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. */
-    ensure(): Promise<void>;
-    /** For a connection being closed: stops a lookup on its way, and its timer. */
-    close(): void;
-    readonly provider: AuthProvider;
-}
 /** A token from `bearer`'s function, kept until a lookup on a 401 finds another, or none. */
 export declare class BearerCredential implements Credential {
     private readonly read;
     private readonly user;
-    /** How long `read` may take: a lookup that never answers would hold up every call after it. */
-    private readonly timeoutMs;
     private token;
     /** The lookup on its way, which every caller shares: only it sets `token`. */
     private looking;
-    /** Stops the lookup on its way, for `close()`. */
-    private stop;
+    /** Bounds `read`: a lookup that never answers would hold up every call after it. */
+    private readonly lookups;
     constructor(read: (userId: string) => string | null | Promise<string | null>, user: string, 
-    /** How long `read` may take: a lookup that never answers would hold up every call after it. */
+    /** How long `read` may take. */
     timeoutMs: number);
-    ensure(): Promise<void>;
+    ensure(): Promise<boolean>;
     close(): void;
     readonly provider: AuthProvider;
     /** One lookup at a time, for first calls and 401s that come together, so none overwrites another's token. */

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACxE;AAED,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,aAAa,CAAC;CAC1F;AAED,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,yFAAyF;IACzF,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAID,gGAAgG;AAChG,eAAO,MAAM,QAAQ,GAAI,MAAM,OAAO,KAAG,UAAU,GAAG,SACqB,CAAC;AAE5E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAgB9D;AAED;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAEtB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW;IADlD,QAAQ,CAAC,IAAI,eAAe;gBACP,IAAI,EAAE,SAAS,GAAG,WAAW;CAGnD;AAED,4FAA4F;AAC5F,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,kBAAkB;gBACnB,KAAK,EAAE,OAAO;CAG3B;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB,2HAA2H;IAC3H,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED,6FAA6F;AAC7F,qBAAa,gBAAiB,YAAW,UAAU;IAQ/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,SAAS;IAV5B,OAAO,CAAC,KAAK,CAAuB;IACpC,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAuC;IACtD,kDAAkD;IAClD,OAAO,CAAC,IAAI,CAA6B;gBAGtB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAChE,IAAI,EAAE,MAAM;IAC7B,+FAA+F;IAC9E,SAAS,EAAE,MAAM;IAG9B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B,KAAK,IAAI,IAAI;IAMb,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAc7B;IAEF,6GAA6G;IAC7G,OAAO,CAAC,IAAI;YASE,MAAM;CAiBrB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -1,72 +1,256 @@
+import { LookupFailed, Lookup, NeedsAuth } from "./credential.js";
+import { OAuthServer, isSecure } from "./oauth.js";
+import { routes } from "./routes.js";
+import { SECRET_BYTES, Sealer } from "./seal.js";
+import { STORE_METHODS } from "./store.js";
+export { LookupFailed, Mismatch, NeedsAuth } from "./credential.js";
 const configs = new WeakMap();
 /** The config an `McpServerAuth` stands for, or undefined if `createMcpAuth` didn't make it. */
 export const configOf = (auth) => 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.bearer(token) })`.
+ * credential: `mcpServer({ auth: mcpAuth.oauth() })`.
  */
 export function createMcpAuth(options) {
     if (typeof options?.userOf !== "function") {
         throw new TypeError("createMcpAuth: userOf must be a function, such as (id) => auth.ownerOf(id)");
     }
-    const names = new Set();
+    for (const name of ["requestUser", "onConnected"]) {
+        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();
     const userOf = (conversationId) => options.userOf(conversationId);
+    function make(kind, bind) {
+        const auth = 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) => {
+        if (!core)
+            throw new TypeError(`${what} needs createMcpAuth({ store, secret, redirectUri })`);
+        return core;
+    };
     return Object.freeze({
         bearer(token) {
             if (typeof token !== "function") {
                 throw new TypeError("bearer: token must be a function that takes a user id and returns their token, or null");
             }
-            const auth = Object.freeze({ kind: "bearer" });
-            configs.set(auth, { kind: "bearer", userOf, token, names });
-            return auth;
+            return make("bearer", (server) => ({
+                credential: (user) => new BearerCredential(token, user, server.timeoutMs),
+                connect: null,
+            }));
         },
+        oauth(oauthOptions = {}) {
+            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) {
+            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) => 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) {
+        const ready = needsStore("connections()");
+        if (typeof userId !== "string" || userId === "")
+            throw new TypeError("connections() needs a userId");
+        const accounts = [];
+        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, server) {
+        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);
+        }
+    }
 }
-/**
- * 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 {
-    kind;
-    name = "NeedsAuth";
-    constructor(kind) {
-        super(kind === "connect" ? "the user has no credential" : "the server refused the user's credential");
-        this.kind = kind;
+/** An `oauth()` server's place on its `McpAuth`. */
+class OAuthBinding {
+    oauth;
+    basePath;
+    constructor(oauth, basePath) {
+        this.oauth = oauth;
+        this.basePath = basePath;
+    }
+    credential(user) {
+        return this.oauth.credential(user);
+    }
+    connect = (conversationId, scope) => {
+        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, basePath) {
+    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;
+    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,
+    };
 }
-/** The app's lookup of a credential failed: made an `McpError` with reason `connection`. */
-export class LookupFailed extends Error {
-    name = "LookupFailed";
-    constructor(cause) {
-        super("the user's credential could not be looked up", { cause });
+function checkOAuth(options) {
+    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 } } : {}) });
 }
+const nonEmpty = (value) => (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 {
     read;
     user;
-    timeoutMs;
     token = null;
     /** The lookup on its way, which every caller shares: only it sets `token`. */
     looking = null;
-    /** Stops the lookup on its way, for `close()`. */
-    stop = null;
+    /** Bounds `read`: a lookup that never answers would hold up every call after it. */
+    lookups;
     constructor(read, user, 
-    /** How long `read` may take: a lookup that never answers would hold up every call after it. */
+    /** How long `read` may take. */
     timeoutMs) {
         this.read = read;
         this.user = user;
-        this.timeoutMs = timeoutMs;
+        this.lookups = new Lookup(timeoutMs, "token");
     }
     async ensure() {
         if (this.token === null)
             await this.look();
         if (this.token === null)
             throw new NeedsAuth("connect");
+        return false;
     }
     close() {
-        this.stop?.();
+        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.
@@ -97,23 +281,54 @@ export class BearerCredential {
         return this.looking;
     }
     async lookup() {
-        let timer;
-        const cut = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`no token within ${this.timeoutMs} ms`)), this.timeoutMs);
-            this.stop = () => reject(new Error("closed while the token was being looked up"));
-        });
         let token;
         try {
-            token = await Promise.race([Promise.resolve().then(() => this.read(this.user)), cut]);
+            token = await this.lookups.run(() => this.read(this.user));
         }
         catch (err) {
             throw new LookupFailed(err);
         }
-        finally {
-            clearTimeout(timer);
-            this.stop = null;
-        }
         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 {
+    make;
+    user;
+    made = null;
+    looking = null;
+    lookups;
+    constructor(make, user, timeoutMs) {
+        this.make = make;
+        this.user = user;
+        this.lookups = new Lookup(timeoutMs, "provider");
+    }
+    async ensure() {
+        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() {
+        this.lookups.stop();
+    }
+    get provider() {
+        // never asked for before ensure() has made it: a connection dials only after
+        if (this.made === null)
+            throw new NeedsAuth("connect");
+        return this.made;
+    }
+}
 //# sourceMappingURL=auth.js.map