@chrischall/mcp-utils 0.1.0

package/dist/auth/index.js

@@ -0,0 +1,267 @@
+/**
+ * Auth resolver skeletons — the shared *shape* of the credential-resolution
+ * logic duplicated across the fleet (resy / opentable / ofw / zola /
+ * signupgenius / creditkarma / canvas / infinitecampus auth.ts).
+ *
+ * This module owns the **skeleton** only. Per-site parameters (which env var,
+ * which cookies to declare, how to parse the session blob, which CSRF input to
+ * scrape) are *injected*; nothing here branches on site identity. Site-specific
+ * OAuth choreographies (e.g. Skylight's `/auth/session` → `/oauth/authorize` →
+ * `/oauth/token` dance) stay per-MCP — they are not a shared shape.
+ *
+ * Four pieces:
+ *  - {@link createAuthResolver} — the three-path resolver
+ *    (env credential → fetchproxy one-shot read → actionable error).
+ *  - {@link resolveAuthPattern} — the four-path variant
+ *    (token → OAuth → session-scrape → fetchproxy), each path an injected
+ *    resolver tried in priority order.
+ *  - {@link sessionLoginFlow} — CSRF-scrape + cookie POST + success-marker,
+ *    the shared CSRF+cookie login primitive (canvas / IC / ofw / signupgenius).
+ *  - {@link createOAuth2Refresher} — an OAuth2 `refresh_token`-grant refresher
+ *    with optional retry and in-flight race-safety.
+ *
+ * Security posture: env reads go through the hardened {@link readEnvVar}
+ * (placeholder / `'null'` / `'undefined'` suppression); thrown errors never
+ * echo the offending secret value and run upstream bodies through
+ * {@link truncateErrorMessage} (redaction + truncation) before surfacing.
+ */
+import { readEnvVar, parseBoolEnv } from '../config/index.js';
+import { truncateErrorMessage, SessionNotAuthenticatedError, createHelpfulError, } from '../errors/index.js';
+import { parseCookieJar } from '../http/index.js';
+/**
+ * Build the canonical **three-path** auth resolver:
+ *
+ *  1. **Env credential** — `envVar` set (after hardened {@link readEnvVar}
+ *     sanitization) → returned directly, no network.
+ *  2. **fetchproxy one-shot read** — unless `disableEnvVar` is truthy, call the
+ *     injected `bootstrap` to snapshot the user's signed-in browser session,
+ *     then `parseTokens` to extract the credential. fetchproxy is invoked once;
+ *     it is never in the hot path.
+ *  3. **Actionable error** — nothing configured: an error naming the env var
+ *     and the sign-in fallback so the user can pick a fix.
+ *
+ * The returned `source` is for diagnostics; callers must treat the credential
+ * as opaque and not branch on it.
+ */
+export function createAuthResolver(opts) {
+    const { envVar, disableEnvVar, bootstrap, bootstrapOptions, parseTokens, serviceName, signInHost, env, } = opts;
+    return async function resolveAuth() {
+        // ── Path 1: env-var credential (hardened against placeholder/sentinel leakage).
+        const envCredential = readEnvVar(envVar, env ? { env } : {});
+        if (envCredential) {
+            return { credential: envCredential, source: 'env' };
+        }
+        // ── Path 2: fetchproxy one-shot fallback (unless explicitly disabled).
+        const disabled = disableEnvVar !== undefined &&
+            parseBoolEnv(disableEnvVar, env ? { env } : {});
+        if (!disabled) {
+            let session;
+            try {
+                session = await bootstrap(bootstrapOptions);
+            }
+            catch (e) {
+                // Surface the fallback failure but point back at the env-var escape
+                // hatch. Redact + truncate the underlying message.
+                throw createHelpfulError(`Auth: no ${envVar} set, and fetchproxy fallback failed: ${truncateErrorMessage(messageOf(e))}`, { hint: `Set ${envVar}, or sign in in your browser and retry.` });
+            }
+            const credential = parseTokens(session);
+            if (credential) {
+                return { credential, source: 'fetchproxy' };
+            }
+            // Bootstrap succeeded but the declared key wasn't present → the browser
+            // tab isn't signed in. This is the stable "go authenticate" condition.
+            throw new SessionNotAuthenticatedError(serviceName, signInHost);
+        }
+        // ── Path 3: nothing configured and fetchproxy disabled.
+        throw createHelpfulError(`Auth: set ${envVar}${signInHost ? `, or sign in at ${signInHost} in your browser` : ', or sign in in your browser'}` +
+            `${disableEnvVar ? ` (unset ${disableEnvVar} if it is set)` : ''}.`, { hint: `Set ${envVar} or sign in in your browser.` });
+    };
+}
+/**
+ * Resolve auth via the four-path priority **token → OAuth → session-scrape →
+ * fetchproxy**. Runs the first *provided* resolver in that order (a missing
+ * resolver = an unconfigured path). A resolver that throws propagates — a
+ * partial-config error (the user's mistake) must surface, not silently fall
+ * through. Throws an actionable error when no path is configured at all.
+ */
+export async function resolveAuthPattern(pattern) {
+    const ordered = [
+        pattern.token,
+        pattern.oauth,
+        pattern.sessionScrape,
+        pattern.fetchproxy,
+    ];
+    for (const resolver of ordered) {
+        if (resolver)
+            return resolver();
+    }
+    throw createHelpfulError('No auth configured. Provide a token, OAuth credentials, login credentials, ' +
+        'or sign in in your browser (fetchproxy fallback).', { hint: 'Set one of the supported credential env vars, or sign in in your browser.' });
+}
+const DEFAULT_LOGIN_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36';
+/** Node's `Headers` may carry multiple `Set-Cookie`s; prefer the spec'd getter. */
+function readSetCookies(headers) {
+    const h = headers;
+    if (typeof h.getSetCookie === 'function')
+        return h.getSetCookie();
+    const raw = headers.get('set-cookie');
+    return raw ? [raw] : [];
+}
+/**
+ * The shared CSRF + cookie login primitive (canvas / IC / ofw / signupgenius):
+ *
+ *  1. GET `loginUrl` — capture the session cookie(s) and scrape the CSRF token
+ *     out of the page with `csrfRegex`.
+ *  2. POST `postUrl` (`application/x-www-form-urlencoded`) with the scraped CSRF
+ *     token, credentials, and any `extraFields`, carrying the GET's cookies.
+ *  3. Merge `Set-Cookie`s from both responses (deduped, deletions dropped) and
+ *     require the `tokenField` cookie as the success marker — its value is the
+ *     returned `token`; its absence means the credentials were rejected.
+ *
+ * Per-site form parameters and the CSRF regex are injected; the flow itself is
+ * site-agnostic.
+ */
+export async function sessionLoginFlow(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const ua = opts.userAgent ?? DEFAULT_LOGIN_UA;
+    const csrfField = opts.csrfField ?? 'csrfToken';
+    const emailField = opts.emailField ?? 'email';
+    const passwordField = opts.passwordField ?? 'password';
+    // Step 1: GET the login page → session cookie + CSRF token.
+    const pageRes = await doFetch(opts.loginUrl, {
+        headers: { 'User-Agent': ua, Accept: 'text/html' },
+    });
+    if (!pageRes.ok) {
+        throw createHelpfulError(`Login page returned ${pageRes.status} ${pageRes.statusText}`, {
+            hint: 'The upstream login page is unreachable; retry later.',
+        });
+    }
+    const pageJar = parseCookieJar(readSetCookies(pageRes.headers));
+    const html = await pageRes.text();
+    const csrfMatch = opts.csrfRegex.exec(html);
+    const csrfToken = csrfMatch?.[1];
+    if (!csrfToken) {
+        throw createHelpfulError('CSRF token not found on the login page.', {
+            hint: 'The login page layout may have changed, or the page failed to load.',
+        });
+    }
+    // Step 2: POST credentials with the scraped CSRF token.
+    const body = new URLSearchParams({
+        [csrfField]: csrfToken,
+        [emailField]: opts.email,
+        [passwordField]: opts.password,
+        ...opts.extraFields,
+    }).toString();
+    const postRes = await doFetch(opts.postUrl, {
+        method: 'POST',
+        redirect: 'manual',
+        headers: {
+            'User-Agent': ua,
+            Accept: 'text/html',
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Referer: opts.loginUrl,
+            ...(pageJar.cookieHeader ? { Cookie: pageJar.cookieHeader } : {}),
+        },
+        body,
+    });
+    // Step 3: merge cookies from both responses; require the success marker.
+    const merged = parseCookieJar([
+        ...readSetCookies(pageRes.headers),
+        ...readSetCookies(postRes.headers),
+    ]);
+    const token = merged.cookies[opts.tokenField];
+    if (!token) {
+        throw createHelpfulError(`Login did not yield a ${opts.tokenField} cookie (status ${postRes.status}) — the credentials were rejected.`, {
+            hint: 'Verify the configured email and password. SSO and 2FA-protected accounts are not supported in this mode.',
+        });
+    }
+    return { token, cookies: merged.cookieHeader };
+}
+const sleep = (ms) => ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+/**
+ * Build a race-safe OAuth2 `refresh_token`-grant refresher. The returned
+ * function POSTs the form-encoded grant to `endpoint` and parses the standard
+ * `{ access_token, refresh_token?, expires_in? }` body.
+ *
+ * Race-safety: concurrent calls share a single in-flight exchange (the
+ * canonical token-refresh-race guard — `skylight`/`canvas`/`creditkarma`/`zola`
+ * all hand-roll this). The in-flight promise is cleared once it settles, so a
+ * later refresh starts fresh and a *rejected* exchange does not poison the next
+ * caller.
+ *
+ * Errors run through {@link truncateErrorMessage} (redaction + truncation)
+ * before surfacing, so an upstream error body can't leak a bearer token or
+ * blow up a tool result.
+ */
+export function createOAuth2Refresher(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const grantType = opts.grantType ?? 'refresh_token';
+    const maxRetries = opts.retry?.count ?? 0;
+    const retryDelayMs = opts.retry?.delayMs ?? 0;
+    let inFlight = null;
+    async function exchangeOnce() {
+        const body = new URLSearchParams({
+            grant_type: grantType,
+            refresh_token: opts.refreshToken,
+            ...opts.params,
+        }).toString();
+        const res = await doFetch(opts.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body,
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => '');
+            throw createHelpfulError(`OAuth2 token refresh failed: ${res.status} ${res.statusText}: ${truncateErrorMessage(errText, 200)}`, { hint: 'The refresh token may be expired or revoked — re-authenticate.' });
+        }
+        const data = (await res.json().catch(() => null));
+        const accessToken = data?.access_token;
+        if (typeof accessToken !== 'string' || accessToken.length === 0) {
+            throw createHelpfulError('OAuth2 token refresh returned no access_token.', {
+                hint: 'The token endpoint returned an unexpected body.',
+            });
+        }
+        const result = { accessToken };
+        if (typeof data?.refresh_token === 'string' && data.refresh_token.length > 0) {
+            result.refreshToken = data.refresh_token;
+        }
+        if (typeof data?.expires_in === 'number') {
+            result.expiresIn = data.expires_in;
+            result.expiresAt = new Date(Date.now() + data.expires_in * 1000);
+        }
+        return result;
+    }
+    async function exchangeWithRetry() {
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await exchangeOnce();
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt < maxRetries)
+                    await sleep(retryDelayMs);
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    return function refresh() {
+        // Coalesce concurrent callers onto one exchange; clear on settle so the
+        // next call starts fresh (and a rejection doesn't stick).
+        if (inFlight)
+            return inFlight;
+        const p = exchangeWithRetry().finally(() => {
+            if (inFlight === p)
+                inFlight = null;
+        });
+        inFlight = p;
+        return p;
+    };
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

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

package/dist/config/index.d.ts

@@ -0,0 +1,86 @@
+/** An environment-variable source: typically `process.env`. */
+export type EnvSource = Record<string, string | undefined>;
+/** Options shared by the env-reading helpers. */
+export interface ReadEnvOptions {
+    /** The source to read from. Defaults to {@link process.env}. */
+    env?: EnvSource;
+    /** Value to return when the variable is unset. */
+    default?: string;
+}
+/**
+ * Read an environment variable defensively.
+ *
+ * The value is trimmed of surrounding whitespace and treated as **unset** when
+ * it is:
+ *  - absent or a non-string,
+ *  - empty / whitespace-only,
+ *  - the literal string `'undefined'` or `'null'`, or
+ *  - an unsubstituted `${...}` placeholder.
+ *
+ * When unset, returns `opts.default` if provided, otherwise `undefined`.
+ *
+ * Consolidates the `readVar`/`readEnv`/`readEnvString`/`sanitizeEnvVar` snippet
+ * duplicated across 12+ MCP servers.
+ */
+export declare function readEnvVar(key: string, opts?: ReadEnvOptions): string | undefined;
+/** Options for {@link requireEnvVar}. */
+export interface RequireEnvOptions {
+    /** The source to read from. Defaults to {@link process.env}. */
+    env?: EnvSource;
+    /** Remediation text appended to the thrown error ("here's how to fix it"). */
+    hint?: string;
+}
+/**
+ * Like {@link readEnvVar} but throws a helpful, value-free error when the
+ * variable is unset (or a placeholder/sentinel). The error names only the
+ * variable and the optional `hint` — never the offending value — so a leaked
+ * placeholder is not echoed back to the caller.
+ */
+export declare function requireEnvVar(key: string, opts?: RequireEnvOptions): string;
+/** Options for {@link parseBoolEnv}. */
+export interface ParseBoolEnvOptions {
+    /** The source to read from. Defaults to {@link process.env}. */
+    env?: EnvSource;
+    /** Result when the variable is unset or unrecognised. Defaults to `false`. */
+    default?: boolean;
+}
+/**
+ * Parse a boolean-ish environment variable. Recognises (case-insensitively)
+ * `1/true/yes/on` as `true` and `0/false/no/off` as `false`. Anything unset,
+ * placeholder/sentinel, or unrecognised falls back to `opts.default` (`false`).
+ *
+ * Consolidates the `['1','true','yes','on'].includes(...)` `*_DISABLE_*` flag
+ * pattern duplicated across the fleet.
+ */
+export declare function parseBoolEnv(key: string, opts?: ParseBoolEnvOptions): boolean;
+/**
+ * Expand a user-provided filesystem path:
+ *  - a leading `~` or `~/...` expands to the user's home directory, and
+ *  - any remaining relative path is resolved against the current working dir.
+ *
+ * Note: `~user` (other-user home lookup) and mid-path `~` are intentionally
+ * NOT expanded — only the current user's home is ever substituted.
+ */
+export declare function expandPath(p: string): string;
+/** Options for {@link loadDotenvSafely}. */
+export interface LoadDotenvOptions {
+    /** Path to the `.env` file. Defaults to dotenv's own resolution (CWD). */
+    path?: string;
+    /**
+     * When `true`, `.env` values overwrite already-set `process.env` entries.
+     * Defaults to `false` so real host-provided env always wins.
+     */
+    override?: boolean;
+}
+/**
+ * Load a `.env` file for local development, swallowing any failure.
+ *
+ * `dotenv` is imported dynamically and the whole thing is wrapped so that a
+ * missing module (e.g. inside an mcpb bundle, where credentials arrive via the
+ * host's `mcp_config.env`) is a silent no-op rather than a crash. Real
+ * environment values take precedence unless `override` is set.
+ *
+ * @returns `true` if a `.env` file was loaded without error, `false` otherwise.
+ */
+export declare function loadDotenvSafely(opts?: LoadDotenvOptions): Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE3D,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,GAAG,SAAS,CAerF;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAO/E;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAQjF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBrF"}

package/dist/config/index.js

@@ -0,0 +1,121 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+/**
+ * Matches a value that is *entirely* an unsubstituted shell-style placeholder,
+ * e.g. `${FOO}` or `${}`. MCP hosts that forward a `.mcp.json` env block without
+ * expanding it can leak these literals into credential slots — treating them as
+ * unset is the canonical defense against the placeholder-leakage class of bugs.
+ *
+ * Only a value that is the placeholder *and nothing else* is suppressed; a real
+ * secret that happens to embed `${` is preserved.
+ */
+const PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
+/**
+ * Read an environment variable defensively.
+ *
+ * The value is trimmed of surrounding whitespace and treated as **unset** when
+ * it is:
+ *  - absent or a non-string,
+ *  - empty / whitespace-only,
+ *  - the literal string `'undefined'` or `'null'`, or
+ *  - an unsubstituted `${...}` placeholder.
+ *
+ * When unset, returns `opts.default` if provided, otherwise `undefined`.
+ *
+ * Consolidates the `readVar`/`readEnv`/`readEnvString`/`sanitizeEnvVar` snippet
+ * duplicated across 12+ MCP servers.
+ */
+export function readEnvVar(key, opts = {}) {
+    const env = opts.env ?? process.env;
+    const raw = env[key];
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.length > 0 &&
+            trimmed !== 'undefined' &&
+            trimmed !== 'null' &&
+            !PLACEHOLDER_RE.test(trimmed)) {
+            return trimmed;
+        }
+    }
+    return opts.default;
+}
+/**
+ * Like {@link readEnvVar} but throws a helpful, value-free error when the
+ * variable is unset (or a placeholder/sentinel). The error names only the
+ * variable and the optional `hint` — never the offending value — so a leaked
+ * placeholder is not echoed back to the caller.
+ */
+export function requireEnvVar(key, opts = {}) {
+    const value = readEnvVar(key, { env: opts.env });
+    if (value === undefined) {
+        const base = `Missing required environment variable ${key}`;
+        throw new Error(opts.hint ? `${base}. ${opts.hint}` : base);
+    }
+    return value;
+}
+const TRUE_TOKENS = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_TOKENS = new Set(['0', 'false', 'no', 'off']);
+/**
+ * Parse a boolean-ish environment variable. Recognises (case-insensitively)
+ * `1/true/yes/on` as `true` and `0/false/no/off` as `false`. Anything unset,
+ * placeholder/sentinel, or unrecognised falls back to `opts.default` (`false`).
+ *
+ * Consolidates the `['1','true','yes','on'].includes(...)` `*_DISABLE_*` flag
+ * pattern duplicated across the fleet.
+ */
+export function parseBoolEnv(key, opts = {}) {
+    const fallback = opts.default ?? false;
+    const raw = readEnvVar(key, { env: opts.env });
+    if (raw === undefined)
+        return fallback;
+    const token = raw.toLowerCase();
+    if (TRUE_TOKENS.has(token))
+        return true;
+    if (FALSE_TOKENS.has(token))
+        return false;
+    return fallback;
+}
+/**
+ * Expand a user-provided filesystem path:
+ *  - a leading `~` or `~/...` expands to the user's home directory, and
+ *  - any remaining relative path is resolved against the current working dir.
+ *
+ * Note: `~user` (other-user home lookup) and mid-path `~` are intentionally
+ * NOT expanded — only the current user's home is ever substituted.
+ */
+export function expandPath(p) {
+    let expanded = p;
+    if (p === '~') {
+        expanded = homedir();
+    }
+    else if (p.startsWith('~/')) {
+        expanded = join(homedir(), p.slice(2));
+    }
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+/**
+ * Load a `.env` file for local development, swallowing any failure.
+ *
+ * `dotenv` is imported dynamically and the whole thing is wrapped so that a
+ * missing module (e.g. inside an mcpb bundle, where credentials arrive via the
+ * host's `mcp_config.env`) is a silent no-op rather than a crash. Real
+ * environment values take precedence unless `override` is set.
+ *
+ * @returns `true` if a `.env` file was loaded without error, `false` otherwise.
+ */
+export async function loadDotenvSafely(opts = {}) {
+    try {
+        const mod = (await import(/* @vite-ignore */ 'dotenv'));
+        const result = mod.config({
+            ...(opts.path !== undefined ? { path: opts.path } : {}),
+            override: opts.override ?? false,
+            quiet: true,
+        });
+        return result.error === undefined;
+    }
+    catch {
+        // dotenv unavailable (bundled runtime) — rely on process.env.
+        return false;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

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

package/dist/errors/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared MCP error classes, error wrapping, and bridge-error discrimination.
+ *
+ * Consolidates the `instanceof`-chains and remediation-message patterns found
+ * in `client.ts` / `auth.ts` across the fleet. Every error carries an optional
+ * `hint` — a "here's how to fix it" string the tool surface can show the user.
+ *
+ * The fetchproxy typed-error hierarchy (`Fetchproxy*Error`) is re-exported, not
+ * reimplemented; {@link classifyBridgeError} is a thin discriminator over it.
+ */
+/** Default seconds to wait before retrying a tripped bot-wall (issue #90 tuning). */
+export declare const DEFAULT_BOT_WALL_RETRY_AFTER_S = 30;
+/** Default truncation budget for upstream error bodies surfaced to clients. */
+export declare const DEFAULT_ERROR_MESSAGE_MAX = 500;
+/**
+ * Base class for every tool-facing error. Carries an optional `hint` —
+ * actionable remediation text ("set ZOLA_REFRESH_TOKEN", "sign in at compass.com")
+ * the tool surface can present separately from the message.
+ */
+export declare class McpToolError extends Error {
+    /** Actionable remediation text, when one applies. */
+    readonly hint?: string;
+    constructor(message: string, opts?: {
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * The user's browser session isn't signed in to the upstream service. Distinct
+ * from a transient bot-wall — this is a stable "go authenticate" condition.
+ */
+export declare class SessionNotAuthenticatedError extends McpToolError {
+    constructor(service?: string, signInHost?: string);
+}
+/**
+ * Transient anti-bot interstitial (PerimeterX / DataDome CAPTCHA). The request
+ * was rate-limited, NOT a missing resource — back off and retry. Kept distinct
+ * from {@link SessionNotAuthenticatedError} so callers don't misclassify a
+ * retryable wall as a stale session (issue #90).
+ */
+export declare class BotWallError extends McpToolError {
+    /** Suggested seconds to wait before retrying the blocked request(s). */
+    readonly retryAfterSeconds: number;
+    constructor(path: string, retryAfterSeconds?: number);
+}
+/** Upstream returned HTTP 429 (or an equivalent rate-limit signal). */
+export declare class RateLimitError extends McpToolError {
+    /** Seconds the upstream asked us to wait, when it told us. */
+    readonly retryAfterSeconds?: number;
+    constructor(service: string, retryAfterSeconds?: number);
+}
+/** Upstream is unreachable (5xx / transport failure) — not the caller's fault. */
+export declare class UnreachableError extends McpToolError {
+    /** Upstream HTTP status, when one was observed. */
+    readonly status?: number;
+    constructor(service: string, status?: number);
+}
+/**
+ * A tool requires a different auth/operation mode than the server is running in
+ * (e.g. a Pro key-mode-only report invoked while in session mode).
+ */
+export declare class ModeMismatchError extends McpToolError {
+    readonly currentMode: string;
+    readonly requiredMode: string;
+    readonly feature: string;
+    constructor(currentMode: string, requiredMode: string, feature: string);
+}
+/** Factory for an {@link McpToolError} with a remediation hint. */
+export declare function createHelpfulError(message: string, opts?: {
+    hint?: string;
+}): McpToolError;
+/**
+ * Redact secrets, then cap an (upstream) error string at `max` characters,
+ * appending a `… [truncated]` marker when clipped.
+ *
+ * Security: redaction runs BEFORE truncation so a token straddling the cut
+ * boundary can't survive in a half-form. Untrusted upstream bodies must always
+ * go through this before reaching a tool result.
+ */
+export declare function truncateErrorMessage(text: string, max?: number): string;
+/** Extract a string message from any thrown value. */
+export declare function messageOf(err: unknown): string;
+/**
+ * Prepend the tool name to an error's context and return an {@link McpToolError},
+ * preserving any `hint` and chaining the original via `cause`. The message is
+ * run through {@link truncateErrorMessage} (redaction + truncation). Re-wrapping
+ * an already-prefixed error does not double-prefix.
+ */
+export declare function wrapToolError(toolName: string, err: unknown): McpToolError;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,qFAAqF;AACrF,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOvE;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,YAAY;gBAChD,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,IAAI,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAuC;CASrF;AAED,uEAAuE;AACvE,qBAAa,cAAe,SAAQ,YAAY;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM;CAOxD;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQ7C;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IAE/C,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAFf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM;CAS3B;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAE1F;AAcD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkC,GAAG,MAAM,CAKlG;AAED,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,YAAY,CAM1E"}