@haikit/mcp 0.32.0 → 0.34.0

package/README.md

@@ -53,10 +53,69 @@ await github.connect(); // at startup: stops here if a declared tool isn't on th
 - `textOf(result)` turns a result into text, for a tool that decides to pass
   some of it on. A cut is always marked in the text.
 
+A server can take each user's own credential instead of the app's. Then each
+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
+  // 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)),
+});
+
+// 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 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

@@ -0,0 +1,151 @@
+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 {
+    /**
+     * 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;
+}
+/** 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.oauth() })`.
+ */
+export declare function createMcpAuth(options: McpAuthOptions): McpAuth;
+/** 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;
+    private token;
+    /** The lookup on its way, which every caller shares: only it sets `token`. */
+    private looking;
+    /** 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. */
+    timeoutMs: number);
+    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. */
+    private look;
+    private lookup;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -0,0 +1,334 @@
+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.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)");
+    }
+    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");
+            }
+            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);
+        }
+    }
+}
+/** 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,
+    };
+}
+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;
+    token = null;
+    /** The lookup on its way, which every caller shares: only it sets `token`. */
+    looking = null;
+    /** Bounds `read`: a lookup that never answers would hold up every call after it. */
+    lookups;
+    constructor(read, user, 
+    /** How long `read` may take. */
+    timeoutMs) {
+        this.read = read;
+        this.user = user;
+        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.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.
+    provider = {
+        // 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. */
+    look() {
+        this.looking ??= this.lookup()
+            .then((token) => (this.token = token))
+            .finally(() => {
+            this.looking = null;
+        });
+        return this.looking;
+    }
+    async lookup() {
+        let token;
+        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 {
+    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

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/credential.d.ts

@@ -0,0 +1,55 @@
+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 declare class NeedsAuth extends Error {
+    readonly kind: "connect" | "reconnect";
+    readonly name = "NeedsAuth";
+    constructor(kind: "connect" | "reconnect");
+}
+/** The app's lookup of a credential failed, or a refresh couldn't be made: made an `McpError` with reason `connection`. */
+export declare class LookupFailed extends Error {
+    readonly name = "LookupFailed";
+    constructor(cause: unknown);
+}
+/**
+ * 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 declare 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 declare class Lookup {
+    private readonly ms;
+    /** Names what's looked up, in the errors. */
+    private readonly what;
+    private stopping;
+    constructor(ms: number, 
+    /** Names what's looked up, in the errors. */
+    what: string);
+    run<T>(look: () => T | Promise<T>): Promise<T>;
+    stop(): void;
+}
+//# sourceMappingURL=credential.d.ts.map

package/dist/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEtF;;;;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,2HAA2H;AAC3H,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,kBAAkB;gBACnB,KAAK,EAAE,OAAO;CAG3B;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,cAAc;CAC5B;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAAC;IACd,8GAA8G;IAC9G,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,mBAAmB,CAAC;CACvD;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,QAAQ,CAA6B;gBAG1B,EAAE,EAAE,MAAM;IAC3B,6CAA6C;IAC5B,IAAI,EAAE,MAAM;IAGzB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAcpD,IAAI,IAAI,IAAI;CAGb"}