openapi-explorer-mcp 0.0.1 → 0.1.0

package/README.md

@@ -19,7 +19,7 @@ the spec and one generic caller.
 | `api_get` | Calls a GET endpoint. |
 | `api_request` | Calls an endpoint with any method. Registered only with `OPENAPI_ALLOW_WRITE`; destructive endpoints need `confirm_danger: true`. |
 | `api_call_log` | Journal of `api_request` calls with ids from responses, for cleaning up. |
-| `api_auth` | Mints tokens through the auth module. Registered only when the module supports it. |
+| `api_credentials` | Keeps credentials for the session or forgets them; shows where the credential of each scheme comes from, never the value. |
 | `recipe` | Markdown recipes for this API. Registered only with `OPENAPI_RECIPES_DIR`. |
 
 ## Configuration
@@ -27,10 +27,9 @@ the spec and one generic caller.
 | Variable | |
 |---|---|
 | `OPENAPI_SPEC_URL` | Required. URL or file path of an OpenAPI 3 JSON spec. URLs are cached on disk and revalidated with ETag. |
-| `OPENAPI_BASE_URL` | Base URL for calls. Required whenever any credential or header is configured; otherwise `servers[0].url` of the spec is used for anonymous calls. |
-| `OPENAPI_AUTH_<SCHEME>` | Credential for a security scheme — see [Authentication](#authentication). |
-| `OPENAPI_HEADER_<NAME>` | A header sent with every call, for specs that don't declare security schemes. `OPENAPI_HEADER_X_API_KEY` sends `x-api-key`. |
-| `OPENAPI_AUTH_MODULE` | Path to an ES module that supplies credentials minted at runtime. |
+| `OPENAPI_BASE_URL` | Base URL for calls. Required when a credential or header is configured in the environment; otherwise `servers[0].url` of the spec is used. |
+| `OPENAPI_AUTH_<SCHEME>` | A permanent credential for a security scheme — see [Authentication](#authentication). |
+| `OPENAPI_HEADER_<NAME>` | A header sent with every call, whatever the spec says. `OPENAPI_HEADER_X_API_KEY` sends `x-api-key`. |
 | `OPENAPI_ENV_FILE` | Env file merged into the environment at startup; variables already set win. |
 | `OPENAPI_ALLOW_WRITE` | `1`, `true` or `yes` registers `api_request`. Off by default. |
 | `OPENAPI_DANGER_FILE` | JSON with danger overrides — see [Danger rules](#danger-rules). |
@@ -63,11 +62,34 @@ the spec and one generic caller.
 ## Authentication
 
 The server doesn't invent headers — it reads them from the spec. `components.securitySchemes` says where a secret
-goes, and each operation's `security` says which schemes it accepts. You only give a scheme its value.
+goes, and each operation's `security` says which schemes it accepts. A scheme takes its value from the first of
+three places that has one:
 
-**Credentials.** `OPENAPI_AUTH_<SCHEME>` holds the value for a scheme; the name is upper-cased with every other
-character replaced by `_`: `x-admin-token` → `OPENAPI_AUTH_X_ADMIN_TOKEN`, `bearer` → `OPENAPI_AUTH_BEARER`. The
-value is placed where the scheme says:
+| Source | Lives | How |
+|---|---|---|
+| the call | one call | `credentials` argument of `api_get` and `api_request` |
+| the session | until the server restarts | `api_credentials` with `set` and `clear` |
+| the environment | as long as the configuration | `OPENAPI_AUTH_<SCHEME>` |
+
+**Permanent credentials** — a static admin token, a service API key — belong in the environment: they stay out of
+the conversation. The variable name is the scheme name upper-cased with every other character replaced by `_`:
+`x-admin-token` → `OPENAPI_AUTH_X_ADMIN_TOKEN`, `bearer` → `OPENAPI_AUTH_BEARER`. A header every call must carry,
+whatever the spec says, goes to `OPENAPI_HEADER_<NAME>`.
+
+**Credentials the model supplies** — a token it just obtained, a key the user pasted into the chat — go through
+`credentials` or `api_credentials`. Keys are scheme names as `api_spec_info` lists them; an `apiKey` scheme also
+accepts its header, query or cookie name, so `X-Api-Key` finds a scheme named `ApiKeyAuth`. When the spec declares
+no security schemes at all, the keys are sent as plain headers.
+
+```
+api_request(method: "POST", endpoint: "POST /auth/login", body: { … })
+api_credentials(set: { "bearer": "<accessToken from the response>" })
+api_get(endpoint: "GET /me")
+```
+
+When a call with a credential gets `401`, the response says so in `note.auth`: obtain a fresh value and set it again.
+
+**Placement.** Whatever the source, the value goes where the scheme says:
 
 | Scheme | Placement |
 |---|---|
@@ -76,38 +98,20 @@ value is placed where the scheme says:
 | `http` `basic` | `Authorization: Basic …` — give `user:password` or an already encoded value |
 
 **Which scheme a call uses.** `security` is a list of alternatives. With `as: "auto"` (the default) the server
-takes the first alternative whose schemes all have credentials. `as` can also name a scheme to force it, or be
-`"anonymous"`. When nothing is configured, a GET is sent anonymously with a note (many GET endpoints declare auth
-but also answer without it); any other method fails with the name of the variable to set.
-
-**Tokens minted at runtime.** `OPENAPI_AUTH_MODULE` points to an ES module whose default export creates a provider.
-The `identity` argument of `api_get` and `api_request` is passed to it as is. Types are exported by the package:
-
-```ts
-import type { AuthProviderFactory } from 'openapi-explorer-mcp';
-
-const createAuth: AuthProviderFactory = ({ baseUrl, timeoutMs, env }) => ({
-  canProvide: (scheme, { identity }) => scheme === 'bearer' && Boolean(identity ?? env.DEFAULT_USER),
-  getCredential: async (scheme, { identity, force }) => mintToken(baseUrl, identity ?? env.DEFAULT_USER, { force, timeoutMs }),
-  // optional: registers api_auth
-  authenticate: async ({ identity, force }) => ({ identity: identity ?? 'default', accessToken: await mintToken(/* … */) }),
-});
-
-export default createAuth;
-```
-
-A static credential from `OPENAPI_AUTH_<SCHEME>` wins over the module for the same scheme. When a call that used a
-module credential gets `401`, the server asks the module again with `force: true` and retries once.
+takes the first alternative whose schemes all have credentials, from any source. `as` can also name a scheme to
+force it, or be `"anonymous"`. When nothing is available, a GET is sent anonymously with a note (many GET endpoints
+declare auth but also answer without it); any other method fails and names every way to supply the credential.
 
 **What keeps credentials safe**
 
-- Only the person configuring the server sets values; no tool accepts headers or tokens, so the model picks a
-  scheme, never a value.
-- Credentials go only to `OPENAPI_BASE_URL`, which must be set explicitly when any credential exists. The spec's
-  `servers` is never trusted with them — the spec is fetched over the network and could point elsewhere.
-- The origin of every request is checked against the base URL before sending; path parameters are URL-encoded.
-- Values never appear in tool output or in the call journal: responses name the scheme, and `api_spec_info` shows
-  only whether a scheme has a credential.
+- Credentials go only to the base URL. The origin of every request is checked against it before sending, and path
+  parameters are URL-encoded, so a path can't redirect a request elsewhere.
+- Credentials from the environment need `OPENAPI_BASE_URL` set explicitly: a server configuration is long-lived and
+  often shared, while the spec's `servers` comes over the network. Credentials the model supplies go to the base URL
+  that `api_spec_info` and `api_credentials` report — `OPENAPI_BASE_URL`, or the first server of the spec.
+- Tool output and the call journal never contain values: they name the scheme and where its credential came from,
+  e.g. `bearer (session)`. A value the model supplies is part of the conversation by nature — keep secrets that
+  must not be there in the environment.
 
 ## Danger rules
 
@@ -130,10 +134,15 @@ Every non-GET operation is `write`, and `destructive` when it is a `DELETE` or i
 npm install
 npm run typecheck
 npm run build      # tsc into dist/
-npm run smoke      # stdio checks against scripts/fixtures/pets.json, no network
+npm run smoke      # stdio checks against scripts/fixtures/pets.json and a local HTTP server, no internet
 npm run check      # all three
+npm run smoke:package  # packs the tarball, installs it in a clean directory and runs the smoke there
 ```
 
+`npm publish` runs `check` and `smoke:package` first. The package depends on TypeScript 5.9 directly: the type
+generator declares TypeScript as a peer dependency, and without the pin npm installs TypeScript 7, whose JavaScript
+API the generator can't use.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/dist/auth.d.ts

@@ -1,51 +1,16 @@
 import { type ExplorerConfig } from './config.js';
 import type { Operation, SecurityScheme } from './spec-index.js';
+/** Where a credential used by a call came from. */
+export type CredentialSource = 'call' | 'session' | 'env';
 /**
- * Per-call context passed to an auth provider.
+ * Credentials the model supplied, resolved against the spec.
  */
-export interface AuthContext {
-    /** Identity from the tool call, e.g. a user id; the provider decides what it means. */
-    identity?: string;
-    /** Ignore cached credentials, e.g. after a 401. */
-    force?: boolean;
+export interface SuppliedCredentials {
+    /** Values keyed by security scheme name. */
+    schemes: Map<string, string>;
+    /** Plain headers keyed by lower-cased name; only for specs that declare no security schemes. */
+    headers: Map<string, string>;
 }
-/**
- * Tokens a provider minted, shown by the api_auth tool.
- */
-export interface AuthSession {
-    /** Who the tokens belong to. */
-    identity: string;
-    /** When the access token expires, ISO 8601. */
-    expiresAt?: string;
-    /** Access token. */
-    accessToken?: string;
-    /** Refresh token. */
-    refreshToken?: string;
-}
-/**
- * Supplies credentials that can't be static, e.g. tokens minted per user.
- */
-export interface AuthProvider {
-    /** Whether the provider can supply a credential for the scheme in this context, without doing I/O. */
-    canProvide(scheme: string, context: AuthContext): boolean;
-    /** Returns the credential value for the scheme. */
-    getCredential(scheme: string, context: AuthContext): Promise<string>;
-    /** Mints or refreshes tokens for an identity; registers the api_auth tool when present. */
-    authenticate?(context: AuthContext): Promise<AuthSession>;
-}
-/**
- * What a provider factory receives.
- */
-export interface AuthProviderOptions {
-    /** OPENAPI_BASE_URL. */
-    baseUrl: string;
-    /** OPENAPI_TIMEOUT_MS. */
-    timeoutMs: number;
-    /** The process environment, with OPENAPI_ENV_FILE already merged in. */
-    env: NodeJS.ProcessEnv;
-}
-/** The default export of an OPENAPI_AUTH_MODULE. */
-export type AuthProviderFactory = (options: AuthProviderOptions) => AuthProvider | Promise<AuthProvider>;
 /** Which security alternative a call uses. */
 export type AuthSelection = {
     mode: 'anonymous';
@@ -55,36 +20,55 @@ export type AuthSelection = {
     schemes: string[];
 };
 /**
- * Imports OPENAPI_AUTH_MODULE and creates its provider.
+ * An empty set of supplied credentials.
  */
-export declare function loadAuthProvider(config: ExplorerConfig): Promise<AuthProvider | undefined>;
+export declare function emptyCredentials(): SuppliedCredentials;
 /**
- * Maps credentials from the environment and an auth provider onto the security schemes of the spec.
+ * Where a scheme puts its value, for humans: "header x-api-key" or "Authorization: Bearer".
+ */
+export declare function placement(scheme: SecurityScheme): string;
+/**
+ * Maps the keys of supplied credentials onto the spec; for a spec without security schemes they are plain headers.
+ */
+export declare function resolveSupplied(input: Record<string, string>, schemes: Record<string, SecurityScheme>): SuppliedCredentials;
+/**
+ * Maps credentials onto the security schemes of the spec. A value passed in a call wins over one kept for the
+ * session, which wins over the environment.
  */
 export declare class Credentials {
     private readonly config;
-    private readonly provider?;
-    constructor(config: ExplorerConfig, provider?: AuthProvider | undefined);
+    private readonly session;
+    constructor(config: ExplorerConfig);
+    /**
+     * Keeps supplied credentials in memory for the rest of the server session.
+     */
+    remember(supplied: SuppliedCredentials): void;
+    /**
+     * Forgets session credentials by key, or all of them for "*"; returns the names that were kept before.
+     */
+    forget(keys: string[], schemes: Record<string, SecurityScheme>): string[];
     /**
      * Where the credential of a scheme comes from, or null when nothing supplies it.
      */
-    source(scheme: string, context?: AuthContext): 'env' | 'module' | null;
+    source(scheme: string, call?: SuppliedCredentials): CredentialSource | null;
     /**
-     * Credential status of a scheme for spec info.
+     * Credential status of a scheme outside a call: its source, or "not configured".
      */
     describe(scheme: string): string;
+    /**
+     * Names of plain headers kept for the session.
+     */
+    sessionHeaders(): string[];
     /**
      * Picks the security alternative for a call: a forced scheme, the first alternative with all credentials, or anonymous.
      */
-    select(op: Operation, as: string, context: AuthContext, schemes: Record<string, SecurityScheme>): AuthSelection;
+    select(op: Operation, as: string, call: SuppliedCredentials, schemes: Record<string, SecurityScheme>): AuthSelection;
     /**
-     * Puts the credentials of the selected schemes into the request; reports whether any came from the provider.
+     * Puts the selected credentials and plain headers into the request; returns what was used, without values.
      */
-    apply(selection: AuthSelection, schemes: Record<string, SecurityScheme>, context: AuthContext, headers: Record<string, string>, url: URL): Promise<{
-        fromProvider: boolean;
-    }>;
+    apply(selection: AuthSelection, schemes: Record<string, SecurityScheme>, call: SuppliedCredentials, headers: Record<string, string>, url: URL): string;
     /**
-     * Tells the user how to supply a credential for a scheme.
+     * Tells how to supply a credential for a scheme.
      */
     private hint;
 }

package/dist/auth.js

@@ -1,20 +1,67 @@
-import { pathToFileURL } from 'node:url';
-import { ConfigError, schemeEnvName, schemeEnvSuffix } from './config.js';
+import { schemeEnvName, schemeEnvSuffix } from './config.js';
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
 /**
- * Imports OPENAPI_AUTH_MODULE and creates its provider.
+ * An empty set of supplied credentials.
  */
-export async function loadAuthProvider(config) {
-    if (!config.authModule || !config.baseUrl)
-        return undefined;
-    const mod = (await import(pathToFileURL(config.authModule).href));
-    if (typeof mod.default !== 'function') {
-        throw new ConfigError(`OPENAPI_AUTH_MODULE must default-export a factory function: ${config.authModule}`);
-    }
-    const provider = (await mod.default({ baseUrl: config.baseUrl, timeoutMs: config.timeoutMs, env: process.env }));
-    if (!provider || typeof provider.canProvide !== 'function' || typeof provider.getCredential !== 'function') {
-        throw new ConfigError('OPENAPI_AUTH_MODULE factory must return an object with canProvide and getCredential');
+export function emptyCredentials() {
+    return { schemes: new Map(), headers: new Map() };
+}
+/**
+ * Where a scheme puts its value, for humans: "header x-api-key" or "Authorization: Bearer".
+ */
+export function placement(scheme) {
+    if (scheme.type === 'apiKey')
+        return `${scheme.in ?? '?'} ${scheme.name ?? '?'}`;
+    if (scheme.type !== 'http')
+        return 'Authorization: Bearer';
+    const kind = (scheme.scheme ?? '').toLowerCase();
+    if (kind === 'bearer')
+        return 'Authorization: Bearer';
+    if (kind === 'basic')
+        return 'Authorization: Basic';
+    return `Authorization: ${scheme.scheme ?? '?'}`;
+}
+/**
+ * Lists the security schemes of a spec with where each one puts its value.
+ */
+function describeSchemes(schemes) {
+    const entries = Object.entries(schemes);
+    return entries.length ? entries.map(([name, scheme]) => `${name} (${placement(scheme)})`).join(', ') : 'none';
+}
+/**
+ * Finds the scheme a key names: the scheme name itself, or the header, query or cookie name of an apiKey scheme.
+ */
+function resolveSchemeName(key, schemes) {
+    if (schemes[key])
+        return key;
+    const lower = key.toLowerCase();
+    const matches = Object.entries(schemes)
+        .filter(([name, scheme]) => name.toLowerCase() === lower || (scheme.type === 'apiKey' && scheme.name?.toLowerCase() === lower))
+        .map(([name]) => name);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1)
+        throw new Error(`"${key}" matches several security schemes (${matches.join(', ')}); use the scheme name`);
+    throw new Error(`unknown credential "${key}"; the spec defines: ${describeSchemes(schemes)}`);
+}
+/**
+ * Maps the keys of supplied credentials onto the spec; for a spec without security schemes they are plain headers.
+ */
+export function resolveSupplied(input, schemes) {
+    const out = emptyCredentials();
+    const hasSchemes = Object.keys(schemes).length > 0;
+    for (const [key, value] of Object.entries(input)) {
+        if (/[\r\n]/.test(value))
+            throw new Error(`the value of "${key}" contains a line break`);
+        if (hasSchemes) {
+            out.schemes.set(resolveSchemeName(key, schemes), value);
+            continue;
+        }
+        if (!HEADER_NAME.test(key))
+            throw new Error(`"${key}" is not a valid header name; the spec declares no security schemes, so keys are sent as headers`);
+        out.headers.set(key.toLowerCase(), value);
     }
-    return provider;
+    return out;
 }
 /**
  * Places a credential where its security scheme says: a header, the query string, a cookie or Authorization.
@@ -25,11 +72,11 @@ function applyScheme(name, scheme, value, headers, url) {
             if (!scheme.name)
                 throw new Error(`security scheme "${name}" has no parameter name`);
             if (scheme.in === 'header')
-                headers[scheme.name] = value;
+                headers[scheme.name.toLowerCase()] = value;
             else if (scheme.in === 'query')
                 url.searchParams.set(scheme.name, value);
             else if (scheme.in === 'cookie')
-                headers.Cookie = [headers.Cookie, `${scheme.name}=${encodeURIComponent(value)}`].filter(Boolean).join('; ');
+                headers.cookie = [headers.cookie, `${scheme.name}=${encodeURIComponent(value)}`].filter(Boolean).join('; ');
             else
                 throw new Error(`security scheme "${name}" uses an unsupported location "${scheme.in}"`);
             return;
@@ -37,66 +84,97 @@ function applyScheme(name, scheme, value, headers, url) {
         case 'http': {
             const kind = (scheme.scheme ?? '').toLowerCase();
             if (kind === 'bearer')
-                headers.Authorization = `Bearer ${value}`;
+                headers.authorization = `Bearer ${value}`;
             else if (kind === 'basic')
-                headers.Authorization = `Basic ${value.includes(':') ? Buffer.from(value).toString('base64') : value}`;
+                headers.authorization = `Basic ${value.includes(':') ? Buffer.from(value).toString('base64') : value}`;
             else
                 throw new Error(`security scheme "${name}" uses an unsupported HTTP scheme "${scheme.scheme}"`);
             return;
         }
         case 'oauth2':
         case 'openIdConnect':
-            headers.Authorization = `Bearer ${value}`;
+            headers.authorization = `Bearer ${value}`;
             return;
         default:
             throw new Error(`security scheme "${name}" has an unsupported type "${scheme.type}"`);
     }
 }
 /**
- * Maps credentials from the environment and an auth provider onto the security schemes of the spec.
+ * Maps credentials onto the security schemes of the spec. A value passed in a call wins over one kept for the
+ * session, which wins over the environment.
  */
 export class Credentials {
     config;
-    provider;
-    constructor(config, provider) {
+    session = emptyCredentials();
+    constructor(config) {
         this.config = config;
-        this.provider = provider;
+    }
+    /**
+     * Keeps supplied credentials in memory for the rest of the server session.
+     */
+    remember(supplied) {
+        for (const [name, value] of supplied.schemes)
+            this.session.schemes.set(name, value);
+        for (const [name, value] of supplied.headers)
+            this.session.headers.set(name, value);
+    }
+    /**
+     * Forgets session credentials by key, or all of them for "*"; returns the names that were kept before.
+     */
+    forget(keys, schemes) {
+        const kept = [...this.session.schemes.keys(), ...this.session.headers.keys()];
+        if (keys.includes('*')) {
+            this.session.schemes.clear();
+            this.session.headers.clear();
+            return kept;
+        }
+        const hasSchemes = Object.keys(schemes).length > 0;
+        const names = keys.map((key) => (hasSchemes ? resolveSchemeName(key, schemes) : key.toLowerCase()));
+        for (const name of names) {
+            this.session.schemes.delete(name);
+            this.session.headers.delete(name);
+        }
+        return kept.filter((name) => names.includes(name));
     }
     /**
      * Where the credential of a scheme comes from, or null when nothing supplies it.
      */
-    source(scheme, context = {}) {
+    source(scheme, call = emptyCredentials()) {
+        if (call.schemes.has(scheme))
+            return 'call';
+        if (this.session.schemes.has(scheme))
+            return 'session';
         if (this.config.schemeCredentials.has(schemeEnvSuffix(scheme)))
             return 'env';
-        return this.provider?.canProvide(scheme, context) ? 'module' : null;
+        return null;
     }
     /**
-     * Credential status of a scheme for spec info.
+     * Credential status of a scheme outside a call: its source, or "not configured".
      */
     describe(scheme) {
-        const source = this.source(scheme);
-        if (source)
-            return source;
-        // canProvide does no I/O by contract, so probing with a placeholder identity is safe and tells whether passing one would help.
-        return this.provider?.canProvide(scheme, { identity: 'identity' }) ? 'module, when an identity is passed' : 'not configured';
+        return this.source(scheme) ?? 'not configured';
+    }
+    /**
+     * Names of plain headers kept for the session.
+     */
+    sessionHeaders() {
+        return [...this.session.headers.keys()];
     }
     /**
      * Picks the security alternative for a call: a forced scheme, the first alternative with all credentials, or anonymous.
      */
-    select(op, as, context, schemes) {
+    select(op, as, call, schemes) {
         if (as === 'anonymous')
             return { mode: 'anonymous' };
         if (as !== 'auto') {
-            if (!schemes[as]) {
-                const known = Object.keys(schemes);
-                throw new Error(`unknown security scheme "${as}"; the spec defines: ${known.length ? known.join(', ') : 'none'}`);
-            }
-            if (!this.source(as, context))
+            if (!schemes[as])
+                throw new Error(`unknown security scheme "${as}"; the spec defines: ${describeSchemes(schemes)}`);
+            if (!this.source(as, call))
                 throw new Error(`no credential for "${as}": ${this.hint(as)}`);
             return { mode: 'credentials', schemes: [as] };
         }
         for (const alternative of op.security) {
-            if (alternative.every((scheme) => this.source(scheme, context))) {
+            if (alternative.every((scheme) => this.source(scheme, call))) {
                 return alternative.length ? { mode: 'credentials', schemes: alternative } : { mode: 'anonymous' };
             }
         }
@@ -110,31 +188,33 @@ export class Credentials {
         throw new Error(`${op.key} requires ${op.security.map((a) => a.join(' + ')).join(' or ')}: ${hints}`);
     }
     /**
-     * Puts the credentials of the selected schemes into the request; reports whether any came from the provider.
+     * Puts the selected credentials and plain headers into the request; returns what was used, without values.
      */
-    async apply(selection, schemes, context, headers, url) {
-        if (selection.mode === 'anonymous')
-            return { fromProvider: false };
-        let fromProvider = false;
-        for (const name of selection.schemes) {
-            const scheme = schemes[name];
-            if (!scheme)
-                throw new Error(`the spec has no security scheme "${name}"`);
-            let value = this.config.schemeCredentials.get(schemeEnvSuffix(name));
-            if (value === undefined) {
-                if (!this.provider)
+    apply(selection, schemes, call, headers, url) {
+        const used = [];
+        if (selection.mode === 'credentials') {
+            for (const name of selection.schemes) {
+                const scheme = schemes[name];
+                if (!scheme)
+                    throw new Error(`the spec has no security scheme "${name}"`);
+                const source = this.source(name, call);
+                const value = call.schemes.get(name) ?? this.session.schemes.get(name) ?? this.config.schemeCredentials.get(schemeEnvSuffix(name));
+                if (!source || value === undefined)
                     throw new Error(`no credential for "${name}": ${this.hint(name)}`);
-                value = await this.provider.getCredential(name, context);
-                fromProvider = true;
+                applyScheme(name, scheme, value, headers, url);
+                used.push(`${name} (${source})`);
             }
-            applyScheme(name, scheme, value, headers, url);
         }
-        return { fromProvider };
+        for (const [name, value] of new Map([...this.session.headers, ...call.headers])) {
+            headers[name] = value;
+            used.push(`header ${name} (${call.headers.has(name) ? 'call' : 'session'})`);
+        }
+        return used.length ? used.join(' + ') : 'anonymous';
     }
     /**
-     * Tells the user how to supply a credential for a scheme.
+     * Tells how to supply a credential for a scheme.
      */
     hint(scheme) {
-        return `set ${schemeEnvName(scheme)}${this.provider ? ' or pass an identity the auth module accepts' : ''}`;
+        return `pass credentials: { "${scheme}": "…" }, keep one with api_credentials, or set ${schemeEnvName(scheme)}`;
     }
 }

package/dist/config.d.ts

@@ -28,8 +28,6 @@ export interface ExplorerConfig {
     instructionsFile?: string;
     /** JSONL journal of api_request calls. */
     callLog: string;
-    /** ES module whose default export creates an auth provider. */
-    authModule?: string;
     /** Headers sent with every call, from OPENAPI_HEADER_<NAME>. */
     staticHeaders: Record<string, string>;
     /** Credentials keyed by the normalized scheme name, from OPENAPI_AUTH_<SCHEME>. */

package/dist/config.js

@@ -10,7 +10,6 @@ export class ConfigError extends Error {
 }
 const AUTH_PREFIX = 'OPENAPI_AUTH_';
 const HEADER_PREFIX = 'OPENAPI_HEADER_';
-const RESERVED_AUTH_KEYS = new Set(['OPENAPI_AUTH_MODULE']);
 /**
  * Normalizes a security scheme name into its environment variable suffix: x-admin-token becomes X_ADMIN_TOKEN.
  */
@@ -130,12 +129,11 @@ export function readConfig(env = process.env) {
         if (key.startsWith(HEADER_PREFIX)) {
             staticHeaders[key.slice(HEADER_PREFIX.length).toLowerCase().replace(/_/g, '-')] = value;
         }
-        else if (key.startsWith(AUTH_PREFIX) && !RESERVED_AUTH_KEYS.has(key)) {
+        else if (key.startsWith(AUTH_PREFIX)) {
             schemeCredentials.set(key.slice(AUTH_PREFIX.length), value);
         }
     }
-    const authModule = optionalPath(env, 'OPENAPI_AUTH_MODULE');
-    if (!baseUrl && (schemeCredentials.size > 0 || Object.keys(staticHeaders).length > 0 || authModule)) {
+    if (!baseUrl && (schemeCredentials.size > 0 || Object.keys(staticHeaders).length > 0)) {
         throw new ConfigError('OPENAPI_BASE_URL is required when credentials or headers are configured: they only go to an origin you set explicitly, never to one taken from the spec');
     }
     const rawCacheDir = env.OPENAPI_CACHE_DIR?.trim();
@@ -157,7 +155,6 @@ export function readConfig(env = process.env) {
         recipesDir: optionalPath(env, 'OPENAPI_RECIPES_DIR'),
         instructionsFile: optionalPath(env, 'OPENAPI_INSTRUCTIONS_FILE'),
         callLog: rawCallLog ? path.resolve(expandHome(rawCallLog)) : path.join(cacheDir, 'calls.jsonl'),
-        authModule,
         staticHeaders,
         schemeCredentials,
     };

package/dist/schemas.d.ts

@@ -50,7 +50,7 @@ export declare const getInput: {
     path_params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
     query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     as: z.ZodDefault<z.ZodString>;
-    identity: z.ZodOptional<z.ZodString>;
+    credentials: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 };
 export declare const requestInput: {
     method: z.ZodEnum<{
@@ -65,14 +65,13 @@ export declare const requestInput: {
     query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     body: z.ZodOptional<z.ZodUnknown>;
     as: z.ZodDefault<z.ZodString>;
-    identity: z.ZodOptional<z.ZodString>;
+    credentials: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reason: z.ZodOptional<z.ZodString>;
     confirm_danger: z.ZodDefault<z.ZodBoolean>;
 };
-export declare const authInput: {
-    identity: z.ZodOptional<z.ZodString>;
-    refresh: z.ZodDefault<z.ZodBoolean>;
-    show_token: z.ZodDefault<z.ZodBoolean>;
+export declare const credentialsInput: {
+    set: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    clear: z.ZodDefault<z.ZodArray<z.ZodString>>;
 };
 export declare const callLogInput: {
     limit: z.ZodDefault<z.ZodNumber>;

package/dist/schemas.js

@@ -9,8 +9,12 @@ const renderMode = z.enum(['outline', 'json']).default('outline').describe('outl
 const as = z
     .string()
     .default('auto')
-    .describe("'auto' uses the first security alternative with configured credentials; 'anonymous' sends none; or a security scheme name from the spec");
-const identity = z.string().optional().describe('Identity passed to the auth module, e.g. a user id');
+    .describe("'auto' uses the first security alternative that has credentials; 'anonymous' sends none; or a security scheme name from the spec");
+const credentialMap = z.record(z.string(), z.string().min(1));
+const credentials = credentialMap
+    .optional()
+    .describe('Credentials for this call only, keyed by security scheme name from api_spec_info; an apiKey scheme also accepts its header name. ' +
+    'They win over api_credentials and the environment. When the spec declares no security schemes, keys are sent as headers');
 const pathParams = z.record(z.string(), z.union([z.string(), z.number()])).default({}).describe('Path parameters');
 const query = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({}).describe('Query-string parameters');
 export const specInfoInput = {
@@ -36,7 +40,7 @@ export const typesInput = {
     include: z.array(z.enum(['request', 'response', 'params'])).default(['request', 'response', 'params']),
     name_prefix: z.string().default('').describe('Prefix for generated type names'),
 };
-export const getInput = { endpoint, path_params: pathParams, query, as, identity };
+export const getInput = { endpoint, path_params: pathParams, query, as, credentials };
 export const requestInput = {
     method,
     endpoint,
@@ -44,14 +48,13 @@ export const requestInput = {
     query,
     body: z.unknown().optional().describe('JSON body'),
     as,
-    identity,
+    credentials,
     reason: z.string().optional().describe('Note for the call journal: why the call was made'),
     confirm_danger: z.boolean().default(false).describe('Required for operations classified as destructive'),
 };
-export const authInput = {
-    identity,
-    refresh: z.boolean().default(false).describe('Mint new tokens even if cached ones are still valid'),
-    show_token: z.boolean().default(false).describe('Return full tokens instead of previews'),
+export const credentialsInput = {
+    set: credentialMap.default({}).describe('Credentials to keep for this server session, keyed like `credentials` in api_get'),
+    clear: z.array(z.string()).default([]).describe('Keys to forget; ["*"] forgets everything kept in this session'),
 };
 export const callLogInput = {
     limit: z.number().int().min(1).max(500).default(50),

package/dist/server.d.ts

@@ -1,4 +1,3 @@
-import { type AuthProvider } from './auth.js';
 import { type ExplorerConfig } from './config.js';
 import { type DangerRules } from './risk.js';
 /**
@@ -6,11 +5,10 @@ import { type DangerRules } from './risk.js';
  */
 export declare class OpenApiExplorerServer {
     private readonly config;
-    private readonly provider;
     private readonly server;
     private readonly store;
     private readonly credentials;
-    constructor(config: ExplorerConfig, rules: DangerRules, provider: AuthProvider | undefined, extraInstructions: string);
+    constructor(config: ExplorerConfig, rules: DangerRules, extraInstructions: string);
     /**
      * Builds the server from environment variables; exits with a readable message when they are wrong.
      */
@@ -36,11 +34,19 @@ export declare class OpenApiExplorerServer {
      */
     private baseUrl;
     /**
-     * Calls an operation: picks credentials, checks the origin, retries once on 401 with fresh provider tokens.
+     * Base URL for calls, or null when there is none; for reports that must not fail.
+     */
+    private baseUrlOrNull;
+    /**
+     * Security schemes with where each puts its value and where its credential comes from — never the value.
+     */
+    private schemeStatus;
+    /**
+     * Calls an operation: resolves and picks credentials, checks the origin, explains a 401 and a 404.
      */
     private performCall;
     /**
-     * Registers every tool; api_request, api_auth and recipe only when configured.
+     * Registers every tool; api_request and recipe only when configured.
      */
     private registerTools;
 }

package/dist/server.js

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { Credentials, loadAuthProvider } from './auth.js';
+import { Credentials, emptyCredentials, placement, resolveSupplied } from './auth.js';
 import { readConfig, schemeEnvName } from './config.js';
 import { buildUrl, send } from './http.js';
 import { appendJsonl, tailJsonl } from './journal.js';
@@ -24,7 +24,7 @@ const BASE_INSTRUCTIONS = [
     '',
     '- Refer to endpoints as "METHOD /path"; operationIds are not always unique.',
     '- Summaries can be missing or wrong — check the path, method and response shape.',
-    '- Authentication follows the security schemes of the spec. api_spec_info shows which schemes have credentials; `as` picks one explicitly.',
+    '- Authentication follows the security schemes of the spec. api_spec_info shows which schemes have credentials. Pass `credentials` for one call or keep them with api_credentials; `as` picks a scheme explicitly.',
     '- Destructive endpoints need confirm_danger: true in api_request.',
 ].join('\n');
 /**
@@ -32,15 +32,13 @@ const BASE_INSTRUCTIONS = [
  */
 export class OpenApiExplorerServer {
     config;
-    provider;
     server;
     store;
     credentials;
-    constructor(config, rules, provider, extraInstructions) {
+    constructor(config, rules, extraInstructions) {
         this.config = config;
-        this.provider = provider;
         this.store = new SpecStore(config, rules);
-        this.credentials = new Credentials(config, provider);
+        this.credentials = new Credentials(config);
         const instructions = extraInstructions ? `${BASE_INSTRUCTIONS}\n\n${extraInstructions}` : BASE_INSTRUCTIONS;
         this.server = new McpServer({ name: config.serverName, version: VERSION }, { capabilities: { tools: {} }, instructions });
         this.registerTools();
@@ -52,9 +50,8 @@ export class OpenApiExplorerServer {
         try {
             const config = readConfig();
             const rules = loadDangerRules(config.dangerFile);
-            const provider = await loadAuthProvider(config);
             const extra = config.instructionsFile ? readFileSync(config.instructionsFile, 'utf8').trim() : '';
-            return new OpenApiExplorerServer(config, rules, provider, extra);
+            return new OpenApiExplorerServer(config, rules, extra);
         }
         catch (error) {
             // stdout carries JSON-RPC, so startup errors go to stderr.
@@ -119,28 +116,48 @@ export class OpenApiExplorerServer {
         throw new Error(`the spec server "${first}" is relative and the spec is a local file; set OPENAPI_BASE_URL`);
     }
     /**
-     * Calls an operation: picks credentials, checks the origin, retries once on 401 with fresh provider tokens.
+     * Base URL for calls, or null when there is none; for reports that must not fail.
+     */
+    baseUrlOrNull(state) {
+        try {
+            return this.baseUrl(state);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Security schemes with where each puts its value and where its credential comes from — never the value.
+     */
+    schemeStatus(schemes) {
+        return Object.entries(schemes).map(([name, scheme]) => ({
+            name,
+            type: scheme.type,
+            placement: placement(scheme),
+            credential: this.credentials.describe(name),
+            env: schemeEnvName(name),
+        }));
+    }
+    /**
+     * Calls an operation: resolves and picks credentials, checks the origin, explains a 401 and a 404.
      */
     async performCall(state, op, args) {
         const base = this.baseUrl(state);
         const origin = new URL(base).origin;
-        const context = { identity: args.identity };
         const schemes = state.index.securitySchemes;
-        const selection = this.credentials.select(op, args.as, context, schemes);
-        const attempt = async (force) => {
-            const url = buildUrl(base, op.path, args.pathParams, args.query);
-            const headers = { ...this.config.staticHeaders };
-            const applied = await this.credentials.apply(selection, schemes, { ...context, force }, headers, url);
-            if (url.origin !== origin)
-                throw new Error(`refusing to send the request to ${url.origin}; only ${origin} is allowed`);
-            return { result: await send(args.method, url, headers, args.body, this.config.timeoutMs), applied };
-        };
-        let { result, applied } = await attempt(false);
-        if (result.status === 401 && applied.fromProvider)
-            ({ result, applied } = await attempt(true));
+        const call = args.credentials ? resolveSupplied(args.credentials, schemes) : emptyCredentials();
+        const selection = this.credentials.select(op, args.as, call, schemes);
+        const url = buildUrl(base, op.path, args.pathParams, args.query);
+        const headers = { ...this.config.staticHeaders };
+        const auth = this.credentials.apply(selection, schemes, call, headers, url);
+        if (url.origin !== origin)
+            throw new Error(`refusing to send the request to ${url.origin}; only ${origin} is allowed`);
+        const result = await send(args.method, url, headers, args.body, this.config.timeoutMs);
         const note = {};
         if (selection.mode === 'anonymous' && selection.note)
             note.auth = selection.note;
+        else if (result.status === 401 && auth !== 'anonymous')
+            note.auth = `the API rejected ${auth}: the credential is wrong or expired — supply a fresh one`;
         if (result.status === 404) {
             const fresh = await this.store.forceRevalidate().catch(() => null);
             note.specRecheck = fresh?.index.byKey.has(op.key)
@@ -148,13 +165,13 @@ export class OpenApiExplorerServer {
                 : 'the path is gone from the spec — the API has probably changed';
         }
         return {
-            auth: selection.mode === 'anonymous' ? 'anonymous' : selection.schemes.join(' + '),
+            auth,
             ...result,
             ...(Object.keys(note).length ? { note } : {}),
         };
     }
     /**
-     * Registers every tool; api_request, api_auth and recipe only when configured.
+     * Registers every tool; api_request and recipe only when configured.
      */
     registerTools() {
         this.server.registerTool('api_spec_info', {
@@ -175,15 +192,7 @@ export class OpenApiExplorerServer {
                 baseUrl: this.config.baseUrl ?? state.index.servers[0] ?? null,
                 counts: state.index.counts,
                 groups,
-                securitySchemes: Object.entries(state.index.securitySchemes).map(([name, scheme]) => ({
-                    name,
-                    type: scheme.type,
-                    ...(scheme.in ? { in: scheme.in } : {}),
-                    ...(scheme.name ? { parameter: scheme.name } : {}),
-                    ...(scheme.scheme ? { scheme: scheme.scheme } : {}),
-                    credential: this.credentials.describe(name),
-                    env: schemeEnvName(name),
-                })),
+                securitySchemes: this.schemeStatus(state.index.securitySchemes),
                 writes: this.config.allowWrite ? 'enabled' : 'disabled (set OPENAPI_ALLOW_WRITE to register api_request)',
                 ...(state.meta.changed ? { changed: state.meta.changed } : {}),
                 ...(state.offline ? { offline: { since: new Date(state.offline.since).toISOString(), reason: state.offline.reason } } : {}),
@@ -355,12 +364,12 @@ export class OpenApiExplorerServer {
             description: 'Calls a GET endpoint and returns the response. Read-only: the method is fixed.',
             inputSchema: schemas.getInput,
             annotations: { readOnlyHint: true, openWorldHint: true },
-        }, ({ endpoint, path_params, query, as, identity }) => this.run(async () => {
+        }, ({ endpoint, path_params, query, as, credentials }) => this.run(async () => {
             const state = await this.store.load();
             const op = resolveEndpoint(state.index, endpoint);
             if (op.method !== 'GET')
                 throw new Error(`${op.key} is not a GET endpoint${this.config.allowWrite ? '; use api_request' : ''}`);
-            const response = await this.performCall(state, op, { method: 'GET', pathParams: path_params, query, as, identity });
+            const response = await this.performCall(state, op, { method: 'GET', pathParams: path_params, query, as, credentials });
             return { key: op.key, ...response, ...this.specNote(state) };
         }));
         if (this.config.allowWrite) {
@@ -369,7 +378,7 @@ export class OpenApiExplorerServer {
                 description: 'Calls an endpoint with any method, including writes. Destructive endpoints need confirm_danger: true. Calls are recorded in api_call_log.',
                 inputSchema: schemas.requestInput,
                 annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-            }, ({ method, endpoint, path_params, query, body, as, identity, reason, confirm_danger }) => this.run(async () => {
+            }, ({ method, endpoint, path_params, query, body, as, credentials, reason, confirm_danger }) => this.run(async () => {
                 const state = await this.store.load();
                 const op = resolveEndpoint(state.index, endpoint);
                 if (method !== op.method)
@@ -377,7 +386,7 @@ export class OpenApiExplorerServer {
                 if (op.danger === 'destructive' && !confirm_danger) {
                     throw new Error(`${op.key} is destructive: ${op.dangerReason}. Repeat with confirm_danger: true if this is intended.`);
                 }
-                const response = await this.performCall(state, op, { method, pathParams: path_params, query, body, as, identity });
+                const response = await this.performCall(state, op, { method, pathParams: path_params, query, body, as, credentials });
                 const responseBody = response.body;
                 appendJsonl(this.config.callLog, {
                     ts: new Date().toISOString(),
@@ -393,25 +402,27 @@ export class OpenApiExplorerServer {
                 return { key: op.key, journaled: true, ...response, ...this.specNote(state) };
             }));
         }
-        const provider = this.provider;
-        if (provider?.authenticate) {
-            this.server.registerTool('api_auth', {
-                title: 'Mint tokens',
-                description: 'Mints or refreshes tokens through the auth module. show_token returns full tokens instead of previews.',
-                inputSchema: schemas.authInput,
-                annotations: { readOnlyHint: true, openWorldHint: true },
-            }, ({ identity, refresh, show_token }) => this.run(async () => {
-                const session = await provider.authenticate({ identity, force: refresh });
-                const preview = (token) => (token ? `${token.slice(0, 12)}…(${token.length})` : undefined);
-                return {
-                    identity: session.identity,
-                    expiresAt: session.expiresAt,
-                    accessToken: show_token ? session.accessToken : preview(session.accessToken),
-                    refreshToken: show_token ? session.refreshToken : preview(session.refreshToken),
-                    ...(show_token ? {} : { note: 'show_token: true returns the full tokens' }),
-                };
-            }));
-        }
+        this.server.registerTool('api_credentials', {
+            title: 'Session credentials',
+            description: 'Keeps credentials in memory for this server session or forgets them, and shows where the credential of each security scheme comes from — never the values. ' +
+                'Keys are scheme names from api_spec_info; an apiKey scheme also accepts its header name. A credential passed in a call wins over a session one, which wins over the environment.',
+            inputSchema: schemas.credentialsInput,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, ({ set, clear }) => this.run(async () => {
+            const state = await this.store.load();
+            const schemes = state.index.securitySchemes;
+            // Resolve first, so a bad key in `set` fails before anything is forgotten.
+            const supplied = resolveSupplied(set, schemes);
+            const forgotten = clear.length ? this.credentials.forget(clear, schemes) : [];
+            this.credentials.remember(supplied);
+            const sessionHeaders = this.credentials.sessionHeaders();
+            return {
+                ...(forgotten.length ? { forgotten } : {}),
+                baseUrl: this.baseUrlOrNull(state),
+                securitySchemes: this.schemeStatus(schemes),
+                ...(sessionHeaders.length ? { sessionHeaders } : {}),
+            };
+        }));
         this.server.registerTool('api_call_log', {
             title: 'Call journal',
             description: 'What api_request has called: endpoint, status and ids from responses — use it to clean up what was created.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-explorer-mcp",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "MCP server for any OpenAPI 3 spec: search endpoints, inspect request and response shapes, generate TypeScript types, and call endpoints with credentials mapped to the spec's security schemes.",
   "license": "MIT",
   "author": "Eugene Trofimov",
@@ -8,13 +8,6 @@
   "bin": {
     "openapi-explorer-mcp": "dist/index.js"
   },
-  "exports": {
-    ".": {
-      "types": "./dist/auth.d.ts",
-      "default": "./dist/auth.js"
-    },
-    "./package.json": "./package.json"
-  },
   "files": [
     "dist",
     "README.md",
@@ -27,7 +20,9 @@
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "typecheck": "tsc --noEmit",
     "smoke": "node scripts/smoke.mjs",
+    "smoke:package": "node scripts/smoke-package.mjs",
     "check": "npm run typecheck && npm run build && npm run smoke",
+    "prepublishOnly": "npm run check && npm run smoke:package",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -50,10 +45,10 @@
   "dependencies": {
     "@hey-api/openapi-ts": "^0.95.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "typescript": "~5.9.3",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^20.19.43",
-    "typescript": "^5.9.3"
+    "@types/node": "^20.19.43"
   }
 }