@novorb/mcp-core 2.1.1 → 3.0.0

package/dist/http-client.js

@@ -1,223 +1,660 @@
 /**
- * @novorb/mcp-core — HTTP Client Factory
+ * @novorb/mcp-core - HTTP client
  *
- * Creates pre-configured axios instances with retry logic and logging.
+ * One hardened HTTP client for every MCP server, built on axios with one in-house retry loop:
+ * - per-request options: headers, query, timeout, signal, responseType (json/text/arraybuffer/stream),
+ *   response size cap, validateStatus, retry overrides, idempotency key
+ * - auth configured once: bearer, basic, custom header, query-param key, async token provider (a 401
+ *   triggers one forced refresh and one replay)
+ * - base URL joining that never doubles a segment; absolute URLs (next-links) are used as-is but only
+ *   toward the base URL's origin or an explicitly allowed one, so credentials never leave
+ * - TLS options through an ESM `node:https` Agent (custom CA, or rejectUnauthorized=false for a
+ *   self-signed test instance)
+ * - `mapError` hook so each service keeps its own error wording; a client-side token bucket
+ * - security: maxRedirects 0, request/response size caps (streams included), errors carry only
+ *   status/statusText/code/method/path (never the raw response, config or headers), secrets masked
+ * - logging through the mcp-core logger only: method, host, path template, status, duration, attempt;
+ *   never query values, headers, bodies or response content
  */
+import { Agent as HttpsAgent } from 'node:https';
+import { Transform } from 'node:stream';
 import axios from 'axios';
-import axiosRetry from 'axios-retry';
-import { getLogger } from './logger.js';
+import { credentialOutcomeFromHttp, currentCredentialScope, parseAuthChallenge, processCredentials, UnknownCredentialError, } from './credentials.js';
+import { paginateRequests } from './pagination.js';
+import { createTokenBucket, TokenBucket } from './rate-limiter.js';
+import { isIdempotentMethod, isRetryableError, parseRetryAfter, retryDelayFor, sleep, throwIfAborted, } from './retry.js';
+import { getLogger } from './utils/logger.js';
+/** The normalized error every failure becomes. Carries no response, config or headers. */
+export class HttpError extends Error {
+    status;
+    statusText;
+    code;
+    method;
+    path;
+    retryAfterMs;
+    /** The upstream OAuth `error_description` (masked), for the credential mapping. */
+    description;
+    /** The parsed `WWW-Authenticate` `error` / `error_description` (masked); never the raw header. */
+    challenge;
+    constructor(fields) {
+        super(fields.message);
+        this.name = 'HttpError';
+        this.method = fields.method;
+        this.path = fields.path;
+        if (fields.status !== undefined)
+            this.status = fields.status;
+        if (fields.statusText !== undefined)
+            this.statusText = fields.statusText;
+        if (fields.code !== undefined)
+            this.code = fields.code;
+        if (fields.retryAfterMs !== undefined)
+            this.retryAfterMs = fields.retryAfterMs;
+        if (fields.description !== undefined)
+            this.description = fields.description;
+        if (fields.challenge !== undefined)
+            this.challenge = fields.challenge;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const MAX_UPSTREAM_MESSAGE = 300;
+/** Provider tokens remembered for masking (the latest ones; older tokens are expired anyway). */
+const MAX_REMEMBERED_TOKENS = 8;
+function asRecord(value) {
+    return value !== null && typeof value === 'object' ? value : undefined;
+}
+function isAbsoluteUrl(path) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(path);
+}
+/**
+ * Joins a path onto a base URL exactly once: one slash between them, nothing else touched. An absolute
+ * URL is returned unchanged (an OData next-link already holds its `/v1.0` segment).
+ */
+export function joinUrl(baseURL, path) {
+    if (isAbsoluteUrl(path))
+        return path;
+    const base = baseURL.replace(/\/+$/, '');
+    const rest = path.replace(/^\/+/, '');
+    return rest ? `${base}/${rest}` : base;
+}
+/** Serialises query params (null/undefined skipped) without touching an existing query string. */
+export function buildQueryString(query, arrayFormat = 'repeat') {
+    if (!query)
+        return '';
+    const parts = [];
+    const enc = encodeURIComponent;
+    for (const [key, value] of Object.entries(query)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            const values = value;
+            if (arrayFormat === 'comma') {
+                parts.push(`${enc(key)}=${values.map((v) => enc(String(v))).join(',')}`);
+            }
+            else {
+                const name = arrayFormat === 'brackets' ? `${key}[]` : key;
+                for (const v of values)
+                    parts.push(`${enc(name)}=${enc(String(v))}`);
+            }
+        }
+        else {
+            parts.push(`${enc(key)}=${enc(String(value))}`);
+        }
+    }
+    return parts.join('&');
+}
+function appendQuery(url, queryString) {
+    if (!queryString)
+        return url;
+    return `${url}${url.includes('?') ? '&' : '?'}${queryString}`;
+}
+/** A fixed API word in a CONFIGURED base path: lowercase letters with `_`/`-` separators (`api`, `rest`). */
+const API_WORD = /^[a-z]+(?:[_-][a-z]+)*$/;
+/** An API version segment: `v4`, `v1.0`, or a bare 1-2 digit number (Trello's `/1/`). */
+const API_VERSION = /^(?:v\d+(?:\.\d+)*|\d{1,2})$/;
+/** The only request-path segment logged without a route template: a leading API prefix or version. */
+const API_PREFIX = /^(?:api|rest|v\d+(?:\.\d+)*|\d{1,2})$/;
+function segmentsOf(path) {
+    return path.split('/').filter((s) => s !== '');
+}
+function matchRoute(segments, routes) {
+    for (const route of routes) {
+        const parts = segmentsOf(route);
+        if (parts.length !== segments.length)
+            continue;
+        if (parts.every((part, i) => part.startsWith(':') || part === segments[i]))
+            return `/${parts.join('/')}`;
+    }
+    return undefined;
+}
+/**
+ * The route shape of a path for logs and errors, never a dynamic value. Fail closed: without a matching
+ * route template every request-path segment becomes `:id` except a leading API prefix or version
+ * (`api`, `rest`, `v4`). The configured base path keeps its API words and versions (`/api/v4`); any
+ * other base segment (a token in the base URL) is masked too. A `routes` template that matches the
+ * path segment for segment (`:name` matches any one segment) is logged instead, with its literal words;
+ * a request's own `logPath` overrides everything.
+ *
+ *   templatePath('/api/v4/projects/7/repository/tags/stable', { basePath: '/api/v4' })
+ *     -> '/api/v4/:id/:id/:id/:id/:id'
+ *   templatePath('/api/v4/projects/7/repository/tags/stable', {
+ *     basePath: '/api/v4', routes: ['/projects/:id/repository/tags/:tag'] })
+ *     -> '/api/v4/projects/:id/repository/tags/:tag'
+ */
+export function templatePath(pathname, options = {}) {
+    const base = segmentsOf(options.basePath ?? '');
+    const all = segmentsOf(pathname);
+    const underBase = base.length > 0 && base.every((s, i) => all[i] === s);
+    const baseOut = underBase ? base.map((s) => (API_WORD.test(s) || API_VERSION.test(s) ? s : ':id')) : [];
+    const rest = underBase ? all.slice(base.length) : all;
+    const prefix = baseOut.length > 0 ? `/${baseOut.join('/')}` : '';
+    const routed = options.routes ? matchRoute(rest, options.routes) : undefined;
+    if (routed !== undefined)
+        return `${prefix}${routed}`;
+    const masked = rest.map((s, i) => (i === 0 && API_PREFIX.test(s) ? s : ':id'));
+    const tail = masked.length > 0 ? `/${masked.join('/')}` : '';
+    return `${prefix}${tail}` || '/';
+}
+function plainHeaders(headers) {
+    const record = asRecord(headers);
+    if (!record)
+        return {};
+    const toJSON = record.toJSON;
+    const source = typeof toJSON === 'function' ? (asRecord(toJSON.call(headers)) ?? {}) : record;
+    const out = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (Array.isArray(value))
+            out[key.toLowerCase()] = value.map(String).join(', ');
+        else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            out[key.toLowerCase()] = String(value);
+        }
+    }
+    return out;
+}
+function firstString(value) {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = firstString(item) ?? firstString(asRecord(item)?.message);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Extracts `{ message, code }` from common upstream error bodies (GitLab, Graph, Jira, Nexus, DT). */
+function upstreamDetails(data, depth = 0) {
+    if (depth > 2 || data === undefined || data === null)
+        return {};
+    if (Buffer.isBuffer(data))
+        return upstreamDetails(data.subarray(0, 4096).toString('utf8'), depth + 1);
+    if (typeof data === 'string') {
+        const text = data.trim();
+        if (!text || text.startsWith('<'))
+            return {};
+        if (text.startsWith('{') || text.startsWith('[')) {
+            try {
+                return upstreamDetails(JSON.parse(text), depth + 1);
+            }
+            catch {
+                // fall through to the plain text
+            }
+        }
+        return { message: text };
+    }
+    const body = asRecord(data);
+    if (!body)
+        return {};
+    const error = asRecord(body.error);
+    const message = firstString(body.message) ??
+        firstString(error?.message) ??
+        firstString(body.error) ??
+        firstString(body.errorMessages) ??
+        firstString(body.errors) ??
+        firstString(body.error_description) ??
+        firstString(body.detail) ??
+        firstString(body.title);
+    const code = firstString(error?.code) ?? (typeof body.code === 'string' ? body.code : undefined);
+    // OAuth-style bodies (GitLab `{ error: "invalid_token", error_description: "Token is expired" }`): the
+    // message stays the `error` code, the description is kept apart for the credential mapping.
+    const description = firstString(body.error_description);
+    return { message, code, ...(description !== undefined && description !== message ? { description } : {}) };
+}
+/**
+ * Caps a response stream and sanitises its errors: a source error (axios emits a raw AxiosError, whose
+ * `config` holds the auth headers) is replaced by a normalized one before it reaches the consumer.
+ */
+function capStream(source, cap, makeError) {
+    let total = 0;
+    const tooLarge = () => makeError('ERR_RESPONSE_TOO_LARGE', `Response exceeds ${cap} bytes`);
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            total += chunk.length;
+            if (total > cap)
+                callback(tooLarge());
+            else
+                callback(null, chunk);
+        },
+    });
+    source.on('error', (err) => {
+        if (err.message.includes('maxContentLength'))
+            limiter.destroy(tooLarge());
+        else {
+            const code = asRecord(err)?.code;
+            limiter.destroy(makeError(typeof code === 'string' ? code : 'ERR_STREAM', 'Response stream failed'));
+        }
+    });
+    limiter.on('error', () => source.destroy());
+    return source.pipe(limiter);
+}
+function isReadable(value) {
+    const record = asRecord(value);
+    return record !== undefined && typeof record.pipe === 'function' && typeof record.destroy === 'function';
+}
 /**
- * MCP HTTP client wrapping axios with retry, logging, and pagination support.
+ * MCP HTTP client. Build one per upstream per process (not per MCP request), so the rate limiter and
+ * the connection pool are shared.
  */
 export class McpHttpClient {
     client;
     logger;
     logContext;
+    config;
+    baseOrigin;
+    basePath;
+    allowedOrigins;
+    bucket;
+    staticSecrets = [];
+    providerTokens = new Set();
     constructor(config) {
-        this.logger = config.logger || getLogger();
-        this.logContext = config.logContext || 'HttpClient';
+        this.config = config;
+        this.logger = config.logger ?? getLogger();
+        this.logContext = config.logContext ?? 'HttpClient';
+        this.baseOrigin = new URL(config.baseURL).origin;
+        this.basePath = new URL(config.baseURL).pathname;
+        this.allowedOrigins = new Set([this.baseOrigin, ...(config.allowedOrigins ?? []).map((o) => new URL(o).origin)]);
+        if (config.rateLimit) {
+            this.bucket = config.rateLimit instanceof TokenBucket ? config.rateLimit : createTokenBucket(config.rateLimit);
+        }
+        this.collectSecrets(config.auth);
+        const httpsAgent = config.tls
+            ? new HttpsAgent({ ca: config.tls.ca, rejectUnauthorized: config.tls.rejectUnauthorized ?? true })
+            : undefined;
         this.client = axios.create({
-            baseURL: config.baseURL,
-            timeout: config.timeout || 30000,
-            // Never follow redirects: the instance carries a static Authorization header, and axios re-sends
-            // request data to a 3xx Location — a malicious/compromised upstream could harvest the credential.
+            timeout: config.timeout ?? DEFAULT_TIMEOUT_MS,
+            // Never follow redirects: requests carry credentials, and a 3xx Location could harvest them.
             maxRedirects: 0,
-            // Cap response/request size (OOM/DoS guard).
-            maxContentLength: 25 * 1024 * 1024,
-            maxBodyLength: 25 * 1024 * 1024,
-            headers: {
-                'Content-Type': 'application/json',
-                ...config.headers,
-            },
-        });
-        axiosRetry(this.client, {
-            retries: config.retries ?? 3,
-            retryDelay: axiosRetry.exponentialDelay,
-            retryCondition: (error) => {
-                // Network/idempotent-request errors are already method-safe. Only ALSO retry 429/5xx for
-                // idempotent methods — never replay a non-idempotent POST/PATCH (duplicate side effects).
-                if (axiosRetry.isNetworkOrIdempotentRequestError(error))
-                    return true;
-                const method = (error.config?.method ?? 'get').toLowerCase();
-                const idempotent = ['get', 'head', 'options', 'put', 'delete'].includes(method);
-                const status = error.response?.status;
-                const retryableStatus = status === 429 || (status !== undefined && status >= 500);
-                return idempotent && retryableStatus;
-            },
+            // Size caps (OOM/DoS guard).
+            maxContentLength: config.maxResponseBytes ?? DEFAULT_MAX_BYTES,
+            maxBodyLength: config.maxRequestBytes ?? DEFAULT_MAX_BYTES,
+            headers: { ...config.headers },
+            transitional: { clarifyTimeoutError: true, silentJSONParsing: true, forcedJSONParsing: true },
+            ...(httpsAgent ? { httpsAgent } : {}),
         });
     }
-    /**
-     * Perform a GET request.
-     */
-    async get(path, params) {
-        const startTime = Date.now();
-        this.logger.debug(`GET ${path}`, this.logContext, { params });
-        try {
-            const response = await this.client.get(path, { params });
-            const duration = Date.now() - startTime;
-            this.logger.debug(`GET ${path} completed`, this.logContext, {
-                status: response.status,
-                duration: `${duration}ms`,
-            });
-            return response.data;
-        }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`GET ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw this.normalizeError(error);
+    collectSecrets(auth) {
+        if (!auth)
+            return;
+        const add = (value) => {
+            if (value.length >= 4)
+                this.staticSecrets.push(value);
+        };
+        switch (auth.type) {
+            case 'bearer':
+                add(auth.token);
+                break;
+            case 'basic':
+                add(auth.password);
+                add(Buffer.from(`${auth.username}:${auth.password}`).toString('base64'));
+                break;
+            case 'header':
+                add(auth.value);
+                break;
+            case 'query':
+                for (const value of Object.values(auth.params)) {
+                    add(value);
+                    add(encodeURIComponent(value));
+                }
+                break;
+            case 'tokenProvider':
+                break;
         }
     }
-    /**
-     * Perform a GET request with pagination.
-     * Reads total count from the X-Total-Count response header.
-     */
-    async getPaginated(path, params) {
-        const startTime = Date.now();
-        this.logger.debug(`GET (paginated) ${path}`, this.logContext, { params });
-        try {
-            const response = await this.client.get(path, { params });
-            const totalCount = parseInt(response.headers['x-total-count'] || '0', 10);
-            const duration = Date.now() - startTime;
-            this.logger.debug(`GET (paginated) ${path} completed`, this.logContext, {
-                status: response.status,
-                totalCount,
-                resultCount: response.data.length,
-                duration: `${duration}ms`,
-            });
-            return { data: response.data, totalCount };
-        }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`GET (paginated) ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw this.normalizeError(error);
+    /** Replaces every configured credential value in `text` with `[REDACTED]`. */
+    maskSecrets(text) {
+        let out = text;
+        for (const secret of [...this.staticSecrets, ...this.providerTokens]) {
+            out = out.split(secret).join('[REDACTED]');
         }
+        return out;
     }
-    /**
-     * Perform a POST request.
-     */
-    async post(path, data, params) {
-        const startTime = Date.now();
-        this.logger.debug(`POST ${path}`, this.logContext);
-        try {
-            const response = await this.client.post(path, data, { params });
-            const duration = Date.now() - startTime;
-            this.logger.debug(`POST ${path} completed`, this.logContext, {
-                status: response.status,
-                duration: `${duration}ms`,
-            });
-            return response.data;
-        }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`POST ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw this.normalizeError(error);
+    async authHeaders(signal, forceRefresh) {
+        const auth = this.config.auth;
+        if (!auth)
+            return {};
+        switch (auth.type) {
+            case 'bearer':
+                return { Authorization: `Bearer ${auth.token}` };
+            case 'basic':
+                return {
+                    Authorization: `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`,
+                };
+            case 'header':
+                return { [auth.name]: auth.value };
+            case 'tokenProvider': {
+                const token = await auth.getToken({ forceRefresh, signal });
+                if (token.length >= 4) {
+                    // Keep only the most recent tokens (a refreshing provider must not grow this for ever).
+                    this.providerTokens.delete(token);
+                    this.providerTokens.add(token);
+                    while (this.providerTokens.size > MAX_REMEMBERED_TOKENS) {
+                        const oldest = this.providerTokens.values().next().value;
+                        if (oldest === undefined)
+                            break;
+                        this.providerTokens.delete(oldest);
+                    }
+                }
+                const scheme = auth.scheme ?? 'Bearer';
+                return { [auth.headerName ?? 'Authorization']: scheme ? `${scheme} ${token}` : token };
+            }
+            case 'query':
+                return {};
         }
     }
-    /**
-     * Perform a PUT request.
-     */
-    async put(path, data, params) {
-        const startTime = Date.now();
-        this.logger.debug(`PUT ${path}`, this.logContext);
+    resolve(req, method) {
+        const joined = joinUrl(this.config.baseURL, req.path);
+        let parsed;
         try {
-            const response = await this.client.put(path, data, { params });
-            const duration = Date.now() - startTime;
-            this.logger.debug(`PUT ${path} completed`, this.logContext, {
-                status: response.status,
-                duration: `${duration}ms`,
-            });
-            return response.data;
+            parsed = new URL(joined);
+        }
+        catch {
+            throw new HttpError({ message: 'Invalid request URL', method, path: '', code: 'ERR_INVALID_URL' });
         }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`PUT ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
+        const path = req.logPath ?? templatePath(parsed.pathname, { basePath: this.basePath, routes: this.config.routes ?? [] });
+        if (!/^https?:$/.test(parsed.protocol) || !this.allowedOrigins.has(parsed.origin)) {
+            throw new HttpError({
+                message: `Refusing to send credentials to a non-allowed origin (${parsed.host})`,
+                method,
+                path,
+                code: 'ERR_ORIGIN_NOT_ALLOWED',
             });
-            throw this.normalizeError(error);
         }
+        const auth = this.config.auth;
+        const query = { ...req.query, ...(auth?.type === 'query' ? auth.params : {}) };
+        return { url: appendQuery(joined, buildQueryString(query, this.config.arrayFormat)), host: parsed.host, path };
     }
-    /**
-     * Perform a PATCH request.
-     */
-    async patch(path, data, params) {
-        const startTime = Date.now();
-        this.logger.debug(`PATCH ${path}`, this.logContext);
-        try {
-            const response = await this.client.patch(path, data, { params });
-            const duration = Date.now() - startTime;
-            this.logger.debug(`PATCH ${path} completed`, this.logContext, {
-                status: response.status,
-                duration: `${duration}ms`,
-            });
-            return response.data;
+    errorInfo(error, method, host, path) {
+        const err = asRecord(error) ?? {};
+        const response = asRecord(err.response);
+        const status = typeof response?.status === 'number' ? response.status : undefined;
+        const statusText = typeof response?.statusText === 'string' && response.statusText ? response.statusText : undefined;
+        const info = { method, host, path };
+        if (status !== undefined) {
+            info.status = status;
+            if (statusText)
+                info.statusText = statusText;
+            const headers = plainHeaders(response?.headers);
+            const retryAfterMs = parseRetryAfter(headers['retry-after']);
+            if (retryAfterMs !== undefined)
+                info.retryAfterMs = retryAfterMs;
+            const details = isReadable(response?.data) ? {} : upstreamDetails(response?.data);
+            if (details.message)
+                info.upstreamMessage = this.maskSecrets(details.message).slice(0, MAX_UPSTREAM_MESSAGE);
+            if (details.code)
+                info.upstreamCode = details.code;
+            if (details.description) {
+                info.upstreamDescription = this.maskSecrets(details.description).slice(0, MAX_UPSTREAM_MESSAGE);
+            }
+            const parsed = parseAuthChallenge(headers['www-authenticate']);
+            const challenge = {};
+            if (parsed.error)
+                challenge.error = this.maskSecrets(parsed.error).slice(0, MAX_UPSTREAM_MESSAGE);
+            if (parsed.description)
+                challenge.description = this.maskSecrets(parsed.description).slice(0, MAX_UPSTREAM_MESSAGE);
+            if (challenge.error !== undefined || challenge.description !== undefined)
+                info.challenge = challenge;
+            info.code = details.code ?? `HTTP_${status}`;
         }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`PATCH ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw this.normalizeError(error);
+        else {
+            const message = typeof err.message === 'string' ? err.message : '';
+            info.code = message.includes('maxContentLength')
+                ? 'ERR_RESPONSE_TOO_LARGE'
+                : message.includes('maxBodyLength')
+                    ? 'ERR_REQUEST_TOO_LARGE'
+                    : typeof err.code === 'string'
+                        ? err.code
+                        : 'ERR_NETWORK';
         }
+        return info;
+    }
+    toHttpError(info) {
+        const fallback = info.upstreamMessage
+            ? info.upstreamMessage
+            : info.status !== undefined
+                ? `HTTP ${info.status}${info.statusText ? ` ${info.statusText}` : ''}`
+                : `Network error (${info.code})`;
+        const mapped = this.config.mapError?.(info);
+        return new HttpError({
+            message: this.maskSecrets(mapped?.message ?? fallback),
+            method: info.method,
+            path: info.path,
+            status: info.status,
+            statusText: info.statusText,
+            code: mapped?.code ?? info.code,
+            retryAfterMs: info.retryAfterMs,
+            ...(info.upstreamDescription !== undefined ? { description: info.upstreamDescription } : {}),
+            ...(info.challenge !== undefined ? { challenge: info.challenge } : {}),
+        });
     }
     /**
-     * Perform a DELETE request.
+     * Where a request's `credential` outcome goes: the current tool call's scope, else the configured
+     * recorder, else the process registry. The name must be declared there (`UnknownCredentialError`
+     * otherwise, before anything is sent: a value passed by mistake is never published).
      */
-    async delete(path, params) {
-        const startTime = Date.now();
-        this.logger.debug(`DELETE ${path}`, this.logContext);
-        try {
-            const response = await this.client.delete(path, { params });
-            const duration = Date.now() - startTime;
-            this.logger.debug(`DELETE ${path} completed`, this.logContext, {
-                status: response.status,
-                duration: `${duration}ms`,
-            });
-            return response.data;
-        }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            this.logger.error(`DELETE ${path} failed`, this.logContext, {
-                duration: `${duration}ms`,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw this.normalizeError(error);
+    credentialRecorder(key) {
+        const recorder = currentCredentialScope() ?? this.config.credentials ?? processCredentials();
+        if (!recorder.has(key))
+            throw new UnknownCredentialError();
+        return recorder;
+    }
+    recordCredential(req, recorder, facts) {
+        if (req.credential === undefined || recorder === undefined)
+            return;
+        const { outcome, ...info } = credentialOutcomeFromHttp(facts);
+        recorder.record(req.credential, outcome, info);
+    }
+    /** Performs a request and returns status, headers and data. */
+    async requestRaw(req) {
+        const method = req.method ?? 'GET';
+        const { url, host, path } = this.resolve(req, method);
+        const recorder = req.credential !== undefined ? this.credentialRecorder(req.credential) : undefined;
+        const policy = req.retry === false ? { retries: 0 } : { ...this.config.retry, ...req.retry };
+        const retries = Math.max(0, policy.retries ?? 3);
+        const replayable = isIdempotentMethod(method) || req.idempotencyKey !== undefined || policy.unsafe === true;
+        const maxBytes = req.maxResponseBytes ?? this.config.maxResponseBytes ?? DEFAULT_MAX_BYTES;
+        const responseType = req.responseType ?? 'json';
+        let forceRefresh = false;
+        let refreshed = false;
+        for (let attempt = 0;;) {
+            throwIfAborted(req.signal);
+            await this.bucket?.acquire(req.signal);
+            let auth;
+            try {
+                auth = await this.authHeaders(req.signal, forceRefresh);
+            }
+            catch (error) {
+                throwIfAborted(req.signal);
+                const detail = error instanceof Error ? error.message : String(error);
+                this.logger.warn(`HTTP ${method} ${host}${path} token provider failed`, this.logContext, {
+                    method,
+                    host,
+                    path,
+                    code: 'ERR_TOKEN_PROVIDER',
+                    attempt,
+                });
+                throw new HttpError({
+                    message: this.maskSecrets(`Token provider failed: ${detail}`).slice(0, MAX_UPSTREAM_MESSAGE),
+                    method,
+                    path,
+                    code: 'ERR_TOKEN_PROVIDER',
+                });
+            }
+            const headers = { ...req.headers, ...auth };
+            if (req.idempotencyKey !== undefined) {
+                headers[this.config.idempotencyKeyHeader ?? 'Idempotency-Key'] = req.idempotencyKey;
+            }
+            const started = Date.now();
+            try {
+                const response = await this.client.request({
+                    method,
+                    url,
+                    data: req.body,
+                    headers,
+                    timeout: req.timeout,
+                    signal: req.signal,
+                    responseType,
+                    maxContentLength: maxBytes,
+                    ...(req.validateStatus ? { validateStatus: req.validateStatus } : {}),
+                });
+                const durationMs = Date.now() - started;
+                this.logger.debug(`HTTP ${method} ${host}${path} ${response.status}`, this.logContext, {
+                    method,
+                    host,
+                    path,
+                    status: response.status,
+                    durationMs,
+                    attempt,
+                });
+                const plain = plainHeaders(response.headers);
+                if (req.credential !== undefined) {
+                    const facts = { status: response.status };
+                    if (response.status >= 400) {
+                        const details = isReadable(response.data) ? {} : upstreamDetails(response.data);
+                        if (details.code)
+                            facts.code = details.code;
+                        if (details.message)
+                            facts.message = this.maskSecrets(details.message);
+                        if (details.description)
+                            facts.description = this.maskSecrets(details.description);
+                        const retryAfterMs = parseRetryAfter(plain['retry-after']);
+                        if (retryAfterMs !== undefined)
+                            facts.retryAfterMs = retryAfterMs;
+                        if (plain['www-authenticate'])
+                            facts.authenticate = plain['www-authenticate'];
+                    }
+                    this.recordCredential(req, recorder, facts);
+                }
+                let data = response.data;
+                if (responseType === 'stream' && isReadable(data)) {
+                    const declared = Number(plain['content-length']);
+                    const streamError = (code, message) => new HttpError({ message, method, path, code });
+                    if (Number.isFinite(declared) && declared > maxBytes) {
+                        data.destroy();
+                        throw streamError('ERR_RESPONSE_TOO_LARGE', `Response exceeds ${maxBytes} bytes`);
+                    }
+                    data = capStream(data, maxBytes, streamError);
+                }
+                return { status: response.status, statusText: response.statusText ?? '', headers: plain, data: data };
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                const durationMs = Date.now() - started;
+                const response = asRecord(asRecord(error)?.response);
+                if (isReadable(response?.data))
+                    response.data.destroy();
+                throwIfAborted(req.signal);
+                const info = this.errorInfo(error, method, host, path);
+                if (info.status === 401 && this.config.auth?.type === 'tokenProvider' && !refreshed) {
+                    refreshed = true;
+                    forceRefresh = true;
+                    this.logger.warn(`HTTP ${method} ${host}${path} 401, refreshing token`, this.logContext, {
+                        method,
+                        host,
+                        path,
+                        status: 401,
+                        durationMs,
+                        attempt,
+                    });
+                    continue;
+                }
+                if (replayable && attempt < retries && isRetryableError(error)) {
+                    const { delayMs, fromRetryAfter } = retryDelayFor(info.retryAfterMs !== undefined ? { retryAfterMs: info.retryAfterMs } : {}, attempt, {
+                        initialDelayMs: policy.initialDelayMs,
+                        maxDelayMs: policy.maxDelayMs,
+                        backoffMultiplier: policy.backoffMultiplier,
+                        maxRetryAfterMs: policy.maxRetryAfterMs,
+                        random: policy.random,
+                    });
+                    this.logger.warn(`HTTP ${method} ${host}${path} retrying`, this.logContext, {
+                        method,
+                        host,
+                        path,
+                        status: info.status,
+                        code: info.code,
+                        durationMs,
+                        attempt,
+                        delayMs,
+                    });
+                    policy.onRetry?.({ attempt, delayMs, fromRetryAfter, status: info.status, code: info.code, method, path });
+                    await sleep(delayMs, req.signal);
+                    attempt++;
+                    continue;
+                }
+                const meta = { method, host, path, status: info.status, code: info.code, durationMs, attempt };
+                const line = `HTTP ${method} ${host}${path} failed`;
+                if (info.status === undefined || info.status >= 500)
+                    this.logger.error(line, this.logContext, meta);
+                else
+                    this.logger.warn(line, this.logContext, meta);
+                // The same facts the thrown HttpError carries, so a later re-classification agrees.
+                this.recordCredential(req, recorder, {
+                    challenge: info.challenge ?? {},
+                    ...(info.status !== undefined ? { status: info.status } : {}),
+                    ...(info.upstreamCode !== undefined ? { code: info.upstreamCode } : {}),
+                    ...(info.upstreamMessage !== undefined ? { message: info.upstreamMessage } : {}),
+                    ...(info.upstreamDescription !== undefined ? { description: info.upstreamDescription } : {}),
+                    ...(info.retryAfterMs !== undefined ? { retryAfterMs: info.retryAfterMs } : {}),
+                });
+                throw this.toHttpError(info);
+            }
         }
     }
+    /** Performs a request and returns the response data. */
+    async request(req) {
+        return (await this.requestRaw(req)).data;
+    }
+    async get(path, config = {}) {
+        return this.request({ ...config, method: 'GET', path });
+    }
+    /** HEAD request; returns the response headers (lower-cased). */
+    async head(path, config = {}) {
+        return (await this.requestRaw({ ...config, method: 'HEAD', path })).headers;
+    }
+    async post(path, body, config = {}) {
+        return this.request({ ...config, method: 'POST', path, body });
+    }
+    async put(path, body, config = {}) {
+        return this.request({ ...config, method: 'PUT', path, body });
+    }
+    async patch(path, body, config = {}) {
+        return this.request({ ...config, method: 'PATCH', path, body });
+    }
+    async delete(path, config = {}) {
+        return this.request({ ...config, method: 'DELETE', path });
+    }
     /**
-     * Get the underlying axios instance for advanced use cases.
+     * Walks an upstream API's pages with a strategy (see `pagination`). Returns an async iterator of
+     * pages plus `items()` and `collect()`; capped by `maxPages` (default 100) and `maxItems`.
      */
+    paginate(request, strategy, options = {}) {
+        return paginateRequests((req) => this.requestRaw(req), request, strategy, options);
+    }
+    /** The underlying axios instance for advanced use cases (bypasses retry, auth and logging). */
     getAxiosInstance() {
         return this.client;
     }
-    normalizeError(error) {
-        if (axios.isAxiosError(error)) {
-            const status = error.response?.status;
-            const statusText = error.response?.statusText;
-            const data = error.response?.data;
-            const message = typeof data === 'object' && data?.message
-                ? data.message
-                : `HTTP ${status} ${statusText}`;
-            const normalized = new Error(message);
-            // Attach only the status — NOT the raw axios `response`. Its `config` carries the request's
-            // Authorization header/token, and the upstream response headers may carry set-cookie/auth
-            // echoes; a consumer logging the thrown error would otherwise leak them.
-            normalized.status = status;
-            normalized.statusText = statusText;
-            return normalized;
-        }
-        return error instanceof Error ? error : new Error(String(error));
-    }
 }
 /**
  * Create a configured HTTP client.
@@ -225,4 +662,5 @@ export class McpHttpClient {
 export function createHttpClient(config) {
     return new McpHttpClient(config);
 }
+export { createTokenBucket, TokenBucket } from './rate-limiter.js';
 //# sourceMappingURL=http-client.js.map