@ferrlabs/mcp-core 7.0.1 → 8.2.1

package/dist/__tests__/api-client.test.js

@@ -1,14 +1,10 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { apiRequest, UnauthorizedError } from '../api-client.js';
+import { apiRequest, UnauthorizedError, UntrustedApiHostError } from '../api-client.js';
 const mockFetch = vi.fn();
 vi.stubGlobal('fetch', mockFetch);
-const clearPersistedTokenMock = vi.fn();
-const clearTokenCacheMock = vi.fn();
-vi.mock('../auth/persistence.js', () => ({
-    clearPersistedToken: () => clearPersistedTokenMock(),
-}));
+const invalidateTokenMock = vi.fn();
 vi.mock('../auth/index.js', () => ({
-    clearTokenCache: () => clearTokenCacheMock(),
+    invalidateToken: (token) => invalidateTokenMock(token),
 }));
 function makeResponse(body, status = 200) {
     const text = body === undefined ? '' : JSON.stringify(body);
@@ -22,8 +18,26 @@ function makeResponse(body, status = 200) {
 describe('apiRequest', () => {
     beforeEach(() => {
         mockFetch.mockReset();
-        clearPersistedTokenMock.mockReset();
-        clearTokenCacheMock.mockReset();
+        invalidateTokenMock.mockReset();
+        invalidateTokenMock.mockResolvedValue(true);
+        delete process.env.FERRLABS_MCP_ALLOWED_API_HOSTS;
+    });
+    it('sends extra headers alongside the defaults', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/agents', { headers: { 'x-ferrfleet-api-version': '2026-08-04' } });
+        const init = mockFetch.mock.calls[0][1];
+        expect(init.headers['x-ferrfleet-api-version']).toBe('2026-08-04');
+        expect(init.headers['Content-Type']).toBe('application/json');
+    });
+    it('does not let an extra header overwrite the credential headers', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/agents', {
+            token: 'real',
+            headers: { Authorization: 'Bearer forged', 'x-api-token': 'forged' },
+        });
+        const init = mockFetch.mock.calls[0][1];
+        expect(init.headers['Authorization']).toBe('Bearer real');
+        expect(init.headers['x-api-token']).toBe('real');
     });
     it('makes a GET request and returns parsed JSON', async () => {
         mockFetch.mockResolvedValue(makeResponse({ status: 'ok' }));
@@ -56,16 +70,52 @@ describe('apiRequest', () => {
         const [, init] = mockFetch.mock.calls[0];
         expect(init.body).toBe(JSON.stringify({ name: 'ci', scopes: ['*'] }));
     });
-    it('clears persisted token and cache on 401 with a token', async () => {
+    it('hands the rejected token to invalidateToken on a 401', async () => {
         mockFetch.mockResolvedValue(makeResponse({ error: 'unauthorized' }, 401));
         await expect(apiRequest('/orgs', { token: 'stale' })).rejects.toBeInstanceOf(UnauthorizedError);
-        expect(clearPersistedTokenMock).toHaveBeenCalledOnce();
-        expect(clearTokenCacheMock).toHaveBeenCalledOnce();
+        expect(invalidateTokenMock).toHaveBeenCalledWith('stale');
     });
-    it('does not clear persisted token on 401 without a token', async () => {
+    it('says nothing was cleared when the token did not come from the file', async () => {
+        invalidateTokenMock.mockResolvedValue(false);
+        mockFetch.mockResolvedValue(makeResponse({ error: 'unauthorized' }, 401));
+        await expect(apiRequest('/orgs', { token: 'from-env' })).rejects.toThrow(/was not read from the token file/);
+    });
+    it('does not invalidate anything on a 401 without a token', async () => {
         mockFetch.mockResolvedValue(makeResponse({ error: 'unauthorized' }, 401));
         await expect(apiRequest('/orgs')).rejects.toThrow('unauthorized');
-        expect(clearPersistedTokenMock).not.toHaveBeenCalled();
-        expect(clearTokenCacheMock).not.toHaveBeenCalled();
+        expect(invalidateTokenMock).not.toHaveBeenCalled();
+    });
+    it('refuses to send a token to a host outside the allowlist', async () => {
+        await expect(apiRequest('/orgs', { token: 'secret', baseUrl: 'https://evil.example.com' })).rejects.toBeInstanceOf(UntrustedApiHostError);
+        expect(mockFetch).not.toHaveBeenCalled();
+    });
+    it('refuses to send a token in clear over http to a remote host', async () => {
+        await expect(apiRequest('/orgs', { token: 'secret', baseUrl: 'http://api.ferrtrack.com' })).rejects.toThrow(/in clear/);
+        expect(mockFetch).not.toHaveBeenCalled();
+    });
+    it('allows an unlisted host once FERRLABS_MCP_ALLOWED_API_HOSTS names it', async () => {
+        process.env.FERRLABS_MCP_ALLOWED_API_HOSTS = 'api.selfhosted.example';
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/orgs', { token: 'secret', baseUrl: 'https://api.selfhosted.example' });
+        expect(mockFetch).toHaveBeenCalledOnce();
+    });
+    it('allows a loopback base URL over http for local development', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/orgs', { token: 'secret', baseUrl: 'http://127.0.0.1:3000' });
+        expect(mockFetch).toHaveBeenCalledOnce();
+    });
+    it('does not gate an unauthenticated call on the host allowlist', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/stats', { baseUrl: 'https://anything.example.com' });
+        expect(mockFetch).toHaveBeenCalledOnce();
+    });
+    it('asks fetch not to follow redirects', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ ok: true }));
+        await apiRequest('/orgs', { token: 'secret' });
+        expect(mockFetch.mock.calls[0][1].redirect).toBe('manual');
+    });
+    it('refuses a redirect rather than walking the credential to Location', async () => {
+        mockFetch.mockResolvedValue(makeResponse(undefined, 302));
+        await expect(apiRequest('/orgs', { token: 'secret' })).rejects.toBeInstanceOf(UntrustedApiHostError);
     });
 });

package/dist/__tests__/tool-text.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-text.test.d.ts.map

package/dist/__tests__/tool-text.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-text.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/tool-text.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/tool-text.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { toToolText, maxToolBytes } from '../tool-text.js';
+describe('toToolText', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv };
+        delete process.env.FERRLABS_MCP_MAX_TOOL_BYTES;
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it('serialises compactly, without the indentation that doubled the cost', () => {
+        const text = toToolText({ a: 1, b: [2, 3] });
+        expect(text).toBe('{"a":1,"b":[2,3]}');
+        expect(text).not.toContain('\n');
+    });
+    it('passes a payload under the ceiling through untouched', () => {
+        const value = { items: ['a', 'b'] };
+        expect(toToolText(value)).toBe(JSON.stringify(value));
+    });
+    it('caps a payload over the ceiling and marks it as incomplete', () => {
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = '200';
+        const text = toToolText({ blob: 'x'.repeat(5000) });
+        expect(Buffer.byteLength(text, 'utf8')).toBeLessThan(1000);
+        expect(text).toMatch(/\[truncated: \d+ of \d+ bytes dropped/);
+        expect(text).toMatch(/must not be read as the whole result/);
+    });
+    it('names the argument that would narrow the result', () => {
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = '100';
+        const text = toToolText({ rows: 'y'.repeat(2000) }, { narrowWith: 'Pass a smaller limit.' });
+        expect(text).toContain('Pass a smaller limit.');
+    });
+    it('keeps the start of the payload so the shape stays readable', () => {
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = '60';
+        const text = toToolText({ id: 'run-1', events: 'z'.repeat(500) });
+        expect(text.startsWith('{"id":"run-1"')).toBe(true);
+    });
+    it('does not cut a multi-byte character into an invalid sequence', () => {
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = '25';
+        const text = toToolText({ n: 'é'.repeat(200) });
+        // A naive slice on the byte buffer lands mid-sequence and yields U+FFFD.
+        expect(text.slice(0, 25)).not.toContain('\uFFFD');
+    });
+    it('falls back to the default ceiling when the env var is not a positive number', () => {
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = 'nonsense';
+        expect(maxToolBytes()).toBe(100_000);
+        process.env.FERRLABS_MCP_MAX_TOOL_BYTES = '-5';
+        expect(maxToolBytes()).toBe(100_000);
+    });
+    it('returns a string payload as-is rather than quoting it', () => {
+        expect(toToolText('already text')).toBe('already text');
+    });
+});

package/dist/api-client.d.ts

@@ -8,10 +8,26 @@ interface RequestOptions {
      * tool call. Falls back to `API_URL` env var, then `api.ferrlabs.com`.
      */
     baseUrl?: string;
+    /**
+     * Extra headers merged into the request, after the defaults and before the
+     * credential headers. Product APIs that negotiate a contract version use
+     * this to send their own header, e.g. `x-ferrfleet-api-version`.
+     */
+    headers?: Record<string, string>;
 }
 export declare class UnauthorizedError extends Error {
     constructor(message: string);
 }
+export declare class UntrustedApiHostError extends Error {
+    constructor(message: string);
+}
+/**
+ * Refuse to attach a credential to a request leaving for an unexpected host,
+ * or travelling in clear off the loopback interface.
+ *
+ * @throws {UntrustedApiHostError}
+ */
+export declare function assertCredentialTarget(url: string): void;
 export declare function apiRequest<T>(path: string, options?: RequestOptions): Promise<T>;
 export {};
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAMA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAmD1F"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAwBA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAUD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBxD;AAED,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAqE1F"}

package/dist/api-client.js

@@ -1,36 +1,102 @@
-import { clearPersistedToken } from './auth/persistence.js';
-import { clearTokenCache } from './auth/index.js';
+import { invalidateToken } from './auth/index.js';
 import { fetchWithTimeout } from './http.js';
 const DEFAULT_API_URL = process.env.API_URL ?? 'https://api.ferrlabs.com';
+/**
+ * Hosts a FerrLabs credential may be sent to.
+ *
+ * Every base URL in this repo comes from an environment variable, so without
+ * a check a typo or a half-controlled variable forwards the token to whatever
+ * host it names. Extend with `FERRLABS_MCP_ALLOWED_API_HOSTS` (comma
+ * separated) for a self-hosted deployment.
+ */
+const DEFAULT_ALLOWED_API_HOSTS = [
+    'api.ferrlabs.com',
+    'api.ferrvault.com',
+    'api.ferrtrack.com',
+    'api.ferrgrowth.com',
+    'api.ferrfleet.com',
+    'api.ferrlens.com',
+];
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '::1'];
 export class UnauthorizedError extends Error {
     constructor(message) {
         super(message);
         this.name = 'UnauthorizedError';
     }
 }
+export class UntrustedApiHostError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UntrustedApiHostError';
+    }
+}
+function allowedApiHosts() {
+    const extra = (process.env.FERRLABS_MCP_ALLOWED_API_HOSTS ?? '')
+        .split(',')
+        .map((h) => h.trim().toLowerCase())
+        .filter((h) => h.length > 0);
+    return [...DEFAULT_ALLOWED_API_HOSTS, ...extra];
+}
+/**
+ * Refuse to attach a credential to a request leaving for an unexpected host,
+ * or travelling in clear off the loopback interface.
+ *
+ * @throws {UntrustedApiHostError}
+ */
+export function assertCredentialTarget(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new UntrustedApiHostError(`refusing to send a token to a malformed URL: ${url}`);
+    }
+    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const loopback = LOOPBACK_HOSTS.includes(host);
+    if (!loopback && parsed.protocol !== 'https:') {
+        throw new UntrustedApiHostError(`refusing to send a token in clear over ${parsed.protocol}// to ${host}`);
+    }
+    if (!loopback && !allowedApiHosts().includes(host)) {
+        throw new UntrustedApiHostError(`refusing to send a token to ${host}, which is not an allowed FerrLabs API host. Set FERRLABS_MCP_ALLOWED_API_HOSTS to permit it.`);
+    }
+}
 export async function apiRequest(path, options = {}) {
-    const { method = 'GET', body, token, baseUrl } = options;
+    const { method = 'GET', body, token, baseUrl, headers: extraHeaders } = options;
     const base = baseUrl ?? DEFAULT_API_URL;
+    const url = `${base}${path}`;
+    if (token)
+        assertCredentialTarget(url);
     const headers = {
         'Content-Type': 'application/json',
         'User-Agent': 'ferrlabs-mcp/4.0.0',
     };
+    for (const [name, value] of Object.entries(extraHeaders ?? {})) {
+        headers[name] = value;
+    }
     if (token) {
         headers['x-api-token'] = token;
         headers['Authorization'] = `Bearer ${token}`;
     }
-    const res = await fetchWithTimeout(`${base}${path}`, {
+    const res = await fetchWithTimeout(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : undefined,
+        // Redirects are followed with the credential headers still attached, so a
+        // 3xx off an API host walks the token to wherever Location points. No
+        // route in these APIs redirects, so treat one as the anomaly it is.
+        redirect: 'manual',
     });
+    if (res.status >= 300 && res.status < 400) {
+        throw new UntrustedApiHostError(`refusing to follow a redirect (HTTP ${res.status}) returned by ${url}`);
+    }
     if (res.status === 204) {
         return undefined;
     }
     if (res.status === 401 && token) {
-        await clearPersistedToken();
-        clearTokenCache();
-        throw new UnauthorizedError('Stored token rejected by the FerrLabs API (likely revoked, expired, or issued under an incompatible format). The token has been cleared — retry the call to trigger a fresh OAuth login.');
+        const cleared = await invalidateToken(token);
+        throw new UnauthorizedError(cleared
+            ? 'Stored token rejected by the FerrLabs API (likely revoked or expired). The stored token has been cleared — retry the call to trigger a fresh OAuth login.'
+            : 'Token rejected by the FerrLabs API. It was not read from the token file, so nothing was cleared: check the token you supplied.');
     }
     const raw = await res.text();
     let data = undefined;

package/dist/auth/__tests__/index.test.js

@@ -37,3 +37,51 @@ describe('getToken', () => {
         expect(a).toBe('fl_cached');
     });
 });
+describe('invalidateToken', () => {
+    const originalEnv = process.env;
+    const clearPersistedTokenMock = vi.fn();
+    beforeEach(() => {
+        vi.resetModules();
+        clearPersistedTokenMock.mockReset();
+        process.env = { ...originalEnv };
+        delete process.env.FERRLABS_API_TOKEN;
+        delete process.env.FERRFLOW_API_TOKEN;
+        delete process.env.FERRLABS_MCP_MODE;
+        vi.doMock('../persistence.js', () => ({
+            clearPersistedToken: () => clearPersistedTokenMock(),
+            readPersistedToken: () => Promise.resolve('fl_from_file'),
+            writePersistedToken: () => Promise.resolve(),
+        }));
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.doUnmock('../persistence.js');
+    });
+    it('deletes the token file when the rejected token came from it', async () => {
+        const { getToken, invalidateToken } = await import('../index.js');
+        const token = await getToken();
+        expect(token).toBe('fl_from_file');
+        await expect(invalidateToken(token)).resolves.toBe(true);
+        expect(clearPersistedTokenMock).toHaveBeenCalledOnce();
+    });
+    it('leaves the token file alone when the rejected token came from the environment', async () => {
+        process.env.FERRLABS_API_TOKEN = 'fl_from_env';
+        const { getToken, invalidateToken } = await import('../index.js');
+        const token = await getToken();
+        await expect(invalidateToken(token)).resolves.toBe(false);
+        expect(clearPersistedTokenMock).not.toHaveBeenCalled();
+    });
+    it('ignores a token this process never cached, so one bad bearer cannot wipe the file', async () => {
+        const { getToken, invalidateToken } = await import('../index.js');
+        await getToken();
+        await expect(invalidateToken('someone-elses-bearer')).resolves.toBe(false);
+        expect(clearPersistedTokenMock).not.toHaveBeenCalled();
+    });
+    it('drops the cache so the next call re-reads the source', async () => {
+        const { getToken, invalidateToken } = await import('../index.js');
+        const first = await getToken();
+        await invalidateToken(first);
+        process.env.FERRLABS_API_TOKEN = 'fl_replacement';
+        expect(await getToken()).toBe('fl_replacement');
+    });
+});

package/dist/auth/__tests__/oauth.test.js

@@ -62,3 +62,47 @@ describe('bindCallbackListener (port fallback)', () => {
         expect(settled.message).toMatch(/state mismatch/);
     });
 });
+describe('bindCallbackListener (port release)', () => {
+    it('frees the port on close, so a later flow can bind it again', async () => {
+        const port = await freePort();
+        const first = await __testOnly.bindCallbackListener(port, 'st');
+        first.callback.catch(() => undefined);
+        expect(first.port).toBe(port);
+        first.close();
+        // Rebinding the same port is the only honest proof it was released:
+        // an unclosed listener makes this throw EADDRINUSE, which is the bug
+        // the flow's own error message told users to clear by hand.
+        const second = await __testOnly.bindCallbackListener(port, 'st');
+        second.callback.catch(() => undefined);
+        expect(second.port).toBe(port);
+        second.close();
+    });
+    it('tolerates close being called twice', async () => {
+        const port = await freePort();
+        const bound = await __testOnly.bindCallbackListener(port, 'st');
+        bound.callback.catch(() => undefined);
+        bound.close();
+        expect(() => bound.close()).not.toThrow();
+    });
+    it('releases the port after it has actually served a connection', async () => {
+        const { Agent, request } = await import('node:http');
+        const port = await freePort();
+        const bound = await __testOnly.bindCallbackListener(port, 'st');
+        bound.callback.catch(() => undefined);
+        const agent = new Agent({ keepAlive: true, maxSockets: 1 });
+        await new Promise((resolve, reject) => {
+            const req = request({ host: '127.0.0.1', port, path: '/nope', agent }, (res) => {
+                res.resume();
+                res.on('end', () => resolve());
+            });
+            req.on('error', reject);
+            req.end();
+        });
+        bound.close();
+        const again = await __testOnly.bindCallbackListener(port, 'st');
+        again.callback.catch(() => undefined);
+        expect(again.port).toBe(port);
+        again.close();
+        agent.destroy();
+    });
+});

package/dist/auth/index.d.ts

@@ -1,3 +1,15 @@
 export declare function getToken(): Promise<string>;
 export declare function clearTokenCache(): void;
+/**
+ * Drop a token the API has just rejected.
+ *
+ * Only deletes the token file when the rejected token is the one this process
+ * read from it. A token supplied through `FERRLABS_API_TOKEN`, or a bearer
+ * that arrived on a single HTTP request, is not ours to delete: in HTTP mode
+ * one client sending a bad bearer would otherwise wipe the server's stored
+ * credential for everyone.
+ *
+ * Returns whether the persisted file was removed.
+ */
+export declare function invalidateToken(token: string): Promise<boolean>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAOA,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAuChD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAUA,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CA0ChD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWrE"}

package/dist/auth/index.js

@@ -1,7 +1,8 @@
-import { readPersistedToken, writePersistedToken } from './persistence.js';
+import { clearPersistedToken, readPersistedToken, writePersistedToken } from './persistence.js';
 import { runLoopbackOauthFlow } from './oauth.js';
 import { getRequestBearerToken } from './context.js';
 let cached = null;
+let cachedSource = null;
 let inFlight = null;
 export async function getToken() {
     const perRequest = getRequestBearerToken();
@@ -15,11 +16,13 @@ export async function getToken() {
     const envToken = process.env.FERRLABS_API_TOKEN ?? process.env.FERRFLOW_API_TOKEN;
     if (envToken) {
         cached = envToken;
+        cachedSource = 'env';
         return envToken;
     }
     const persisted = await readPersistedToken();
     if (persisted) {
         cached = persisted;
+        cachedSource = 'file';
         return persisted;
     }
     if (process.env.FERRLABS_MCP_NO_OAUTH === '1') {
@@ -30,6 +33,7 @@ export async function getToken() {
             const { token } = await runLoopbackOauthFlow();
             await writePersistedToken(token);
             cached = token;
+            cachedSource = 'oauth';
             return token;
         })().finally(() => {
             inFlight = null;
@@ -39,5 +43,28 @@ export async function getToken() {
 }
 export function clearTokenCache() {
     cached = null;
+    cachedSource = null;
     inFlight = null;
 }
+/**
+ * Drop a token the API has just rejected.
+ *
+ * Only deletes the token file when the rejected token is the one this process
+ * read from it. A token supplied through `FERRLABS_API_TOKEN`, or a bearer
+ * that arrived on a single HTTP request, is not ours to delete: in HTTP mode
+ * one client sending a bad bearer would otherwise wipe the server's stored
+ * credential for everyone.
+ *
+ * Returns whether the persisted file was removed.
+ */
+export async function invalidateToken(token) {
+    if (cached !== token)
+        return false;
+    const source = cachedSource;
+    clearTokenCache();
+    if (source === 'file' || source === 'oauth') {
+        await clearPersistedToken();
+        return true;
+    }
+    return false;
+}

package/dist/auth/oauth.d.ts

@@ -10,6 +10,11 @@ interface CallbackResult {
 interface BoundListener {
     port: number;
     callback: Promise<CallbackResult>;
+    /**
+     * Release the port. Safe to call more than once, and on a listener that
+     * already served its callback.
+     */
+    close: () => void;
 }
 /**
  * Bind a loopback HTTP listener on `port` and return a resolved promise

package/dist/auth/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAYA,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C;AAwBD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,iBAAS,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwDzF;AA4BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,UAAU;;CAEtB,CAAC;AAEF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAoD3E"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAYA,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C;AAwBD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAClC;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,iBAAS,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmEzF;AA4BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,UAAU;;CAEtB,CAAC;AAEF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CA8D3E"}

package/dist/auth/oauth.js

@@ -80,6 +80,17 @@ function bindCallbackListener(port, expectedState) {
                 rejectCallback(err instanceof Error ? err : new Error(String(err)));
             }
         });
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            // `close()` alone waits for open sockets, and a browser that kept the
+            // connection alive never yields one, so drop them first. Defensive:
+            // the tests cover the release, not this specific path.
+            server.closeAllConnections();
+            server.close();
+        };
         const onBindError = (err) => {
             server.removeListener('listening', onListening);
             rejectBound(err);
@@ -89,7 +100,7 @@ function bindCallbackListener(port, expectedState) {
             // Once bound successfully, route runtime errors into the callback
             // promise (e.g. unexpected close after we've started serving).
             server.on('error', (err) => rejectCallback(err));
-            resolveBound({ port, callback });
+            resolveBound({ port, callback, close });
         };
         server.once('error', onBindError);
         server.once('listening', onListening);
@@ -141,7 +152,7 @@ export async function runLoopbackOauthFlow() {
         const detail = bindErrors.map((e) => `${e.port}: ${e.error}`).join('; ');
         throw new Error(`Could not bind any of the loopback ports (${REDIRECT_PORTS.join(', ')}). ${detail}. Close whatever is holding the ports (commonly an MCP subprocess from another Claude session stuck in OAuth), then retry.`);
     }
-    const { port, callback: callbackPromise } = bound;
+    const { port, callback: callbackPromise, close } = bound;
     const redirectUri = `http://127.0.0.1:${port}/cb`;
     const authorizeUrl = new URL(`${AUTH_BASE}/authorize`);
     authorizeUrl.searchParams.set('client_id', CLIENT_ID);
@@ -151,10 +162,21 @@ export async function runLoopbackOauthFlow() {
     authorizeUrl.searchParams.set('code_challenge_method', 'S256');
     authorizeUrl.searchParams.set('state', state);
     openBrowser(authorizeUrl.toString());
+    let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error(`OAuth flow timed out after ${AUTH_TIMEOUT_MS / 1000}s. If your browser didn't open, visit: ${authorizeUrl.toString()}`)), AUTH_TIMEOUT_MS);
+        timer = setTimeout(() => reject(new Error(`OAuth flow timed out after ${AUTH_TIMEOUT_MS / 1000}s. If your browser didn't open, visit: ${authorizeUrl.toString()}`)), AUTH_TIMEOUT_MS);
     });
-    const { code } = await Promise.race([callbackPromise, timeoutPromise]);
-    const token = await exchangeCodeForToken(code, pkce.verifier, redirectUri);
-    return { token };
+    try {
+        const { code } = await Promise.race([callbackPromise, timeoutPromise]);
+        const token = await exchangeCodeForToken(code, pkce.verifier, redirectUri);
+        return { token };
+    }
+    finally {
+        // Every exit closes the listener: a timeout, a CSRF mismatch, a failed
+        // exchange, and the happy path. Leaving it bound is what holds ports
+        // 54321/54322 until the process dies, which is the failure the bind
+        // error above tells the user to go and clear by hand.
+        clearTimeout(timer);
+        close();
+    }
 }

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { runMcp, type RunMcpOptions } from './runner.js';
-export { apiRequest, UnauthorizedError } from './api-client.js';
-export { getToken, clearTokenCache } from './auth/index.js';
+export { apiRequest, UnauthorizedError, UntrustedApiHostError } from './api-client.js';
+export { getToken, clearTokenCache, invalidateToken } from './auth/index.js';
 export { runWithAuthContext, getRequestBearerToken } from './auth/context.js';
 export { readPackageVersion } from './version.js';
 export type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { fetchWithTimeout, fetchTimeoutMs } from './http.js';
+export { toToolText, maxToolBytes } from './tool-text.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 export { runMcp } from './runner.js';
-export { apiRequest, UnauthorizedError } from './api-client.js';
-export { getToken, clearTokenCache } from './auth/index.js';
+export { apiRequest, UnauthorizedError, UntrustedApiHostError } from './api-client.js';
+export { getToken, clearTokenCache, invalidateToken } from './auth/index.js';
 export { runWithAuthContext, getRequestBearerToken } from './auth/context.js';
 export { readPackageVersion } from './version.js';
+export { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { fetchWithTimeout, fetchTimeoutMs } from './http.js';
+export { toToolText, maxToolBytes } from './tool-text.js';

package/dist/tool-text.d.ts

@@ -0,0 +1,12 @@
+export declare function maxToolBytes(): number;
+interface ToolTextOptions {
+    /**
+     * What the caller can change to get less back, e.g. "pass a smaller
+     * `limit`". Appended to the truncation notice so the assistant can recover
+     * on its own instead of retrying the same call.
+     */
+    narrowWith?: string;
+}
+export declare function toToolText(value: unknown, options?: ToolTextOptions): string;
+export {};
+//# sourceMappingURL=tool-text.d.ts.map

package/dist/tool-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-text.d.ts","sourceRoot":"","sources":["../src/tool-text.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED,UAAU,eAAe;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAyBD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAkBhF"}

package/dist/tool-text.js

@@ -0,0 +1,46 @@
+const DEFAULT_MAX_TOOL_BYTES = 100_000;
+export function maxToolBytes() {
+    const raw = process.env.FERRLABS_MCP_MAX_TOOL_BYTES;
+    if (!raw)
+        return DEFAULT_MAX_TOOL_BYTES;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_TOOL_BYTES;
+}
+/**
+ * Serialise a tool payload for the model, with a ceiling.
+ *
+ * Compact rather than pretty-printed: indentation roughly doubles the token
+ * cost and a model reader gains nothing from it.
+ *
+ * Truncation is announced in the returned text. Silently cutting a payload is
+ * worse than sending too much, because the assistant then reasons over a
+ * fragment it believes is complete.
+ */
+/**
+ * Cut to at most `maxBytes`, stepping back off a UTF-8 continuation byte so
+ * the last character is never left half-decoded as U+FFFD.
+ */
+function sliceUtf8(input, maxBytes) {
+    const buf = Buffer.from(input, 'utf8');
+    if (buf.length <= maxBytes)
+        return input;
+    let end = maxBytes;
+    while (end > 0 && (buf[end] & 0b1100_0000) === 0b1000_0000)
+        end--;
+    return buf.subarray(0, end).toString('utf8');
+}
+export function toToolText(value, options = {}) {
+    const serialised = typeof value === 'string' ? value : JSON.stringify(value);
+    if (serialised === undefined)
+        return 'null';
+    const budget = maxToolBytes();
+    const total = Buffer.byteLength(serialised, 'utf8');
+    if (total <= budget)
+        return serialised;
+    const kept = sliceUtf8(serialised, budget);
+    const dropped = total - Buffer.byteLength(kept, 'utf8');
+    const narrow = options.narrowWith ? ` ${options.narrowWith}` : '';
+    return (`${kept}\n\n[truncated: ${dropped} of ${total} bytes dropped, ` +
+        `so this payload is incomplete and must not be read as the whole result.${narrow} ` +
+        `Raise FERRLABS_MCP_MAX_TOOL_BYTES to change the ${budget}-byte ceiling.]`);
+}

package/dist/transports/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAM3D;AAED,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAK7F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGrF;AAYD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAQA;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAoCD,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiJ5E"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAM3D;AAED,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAK7F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGrF;AAYD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAQA;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAoCD,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+J5E"}

package/dist/transports/http.js

@@ -133,6 +133,11 @@ export async function startHttpServer(opts) {
             }));
             return;
         }
+        // In stateless mode nothing ever retains what we build here, so the pair
+        // has to be torn down once the response is written. Left alone, every
+        // request adds an McpServer and a transport that live until the process
+        // does.
+        let disposable;
         if (!transport) {
             let createdSessionId;
             transport = new StreamableHTTPServerTransport({
@@ -151,9 +156,19 @@ export async function startHttpServer(opts) {
             };
             const server = opts.createServer();
             await server.connect(transport);
+            if (stateless)
+                disposable = { server, transport };
         }
         const body = await readJsonBody(req);
-        await runWithAuthContext({ bearerToken }, () => transport.handleRequest(req, res, body));
+        try {
+            await runWithAuthContext({ bearerToken }, () => transport.handleRequest(req, res, body));
+        }
+        finally {
+            if (disposable) {
+                await disposable.transport.close().catch(() => undefined);
+                await disposable.server.close().catch(() => undefined);
+            }
+        }
     }
     function applyCorsHeaders(req, res) {
         res.setHeader('Vary', 'Origin');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferrlabs/mcp-core",
-  "version": "7.0.1",
+  "version": "8.2.1",
   "description": "Shared core for FerrLabs MCP servers — auth, transports (stdio + Streamable HTTP), api-client, runner",
   "license": "MPL-2.0",
   "type": "module",