@ferrlabs/mcp-core 6.1.0 → 6.2.2

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

@@ -1,7 +1,15 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { apiRequest } from '../api-client.js';
+import { apiRequest, UnauthorizedError } 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(),
+}));
+vi.mock('../auth/index.js', () => ({
+    clearTokenCache: () => clearTokenCacheMock(),
+}));
 function makeResponse(body, status = 200) {
     const text = body === undefined ? '' : JSON.stringify(body);
     return {
@@ -14,6 +22,8 @@ function makeResponse(body, status = 200) {
 describe('apiRequest', () => {
     beforeEach(() => {
         mockFetch.mockReset();
+        clearPersistedTokenMock.mockReset();
+        clearTokenCacheMock.mockReset();
     });
     it('makes a GET request and returns parsed JSON', async () => {
         mockFetch.mockResolvedValue(makeResponse({ status: 'ok' }));
@@ -46,4 +56,16 @@ 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 () => {
+        mockFetch.mockResolvedValue(makeResponse({ error: 'unauthorized' }, 401));
+        await expect(apiRequest('/v1/orgs', { token: 'stale' })).rejects.toBeInstanceOf(UnauthorizedError);
+        expect(clearPersistedTokenMock).toHaveBeenCalledOnce();
+        expect(clearTokenCacheMock).toHaveBeenCalledOnce();
+    });
+    it('does not clear persisted token on 401 without a token', async () => {
+        mockFetch.mockResolvedValue(makeResponse({ error: 'unauthorized' }, 401));
+        await expect(apiRequest('/v1/orgs')).rejects.toThrow('unauthorized');
+        expect(clearPersistedTokenMock).not.toHaveBeenCalled();
+        expect(clearTokenCacheMock).not.toHaveBeenCalled();
+    });
 });

package/dist/api-client.d.ts

@@ -9,6 +9,9 @@ interface RequestOptions {
      */
     baseUrl?: string;
 }
+export declare class UnauthorizedError extends Error {
+    constructor(message: string);
+}
 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":"AAEA,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,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CA2C1F"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAKA,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;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAmD1F"}

package/dist/api-client.js

@@ -1,4 +1,12 @@
+import { clearPersistedToken } from './auth/persistence.js';
+import { clearTokenCache } from './auth/index.js';
 const DEFAULT_API_URL = process.env.API_URL ?? 'https://api.ferrlabs.com';
+export class UnauthorizedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnauthorizedError';
+    }
+}
 export async function apiRequest(path, options = {}) {
     const { method = 'GET', body, token, baseUrl } = options;
     const base = baseUrl ?? DEFAULT_API_URL;
@@ -18,6 +26,11 @@ export async function apiRequest(path, options = {}) {
     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 raw = await res.text();
     let data = undefined;
     if (raw) {

package/dist/auth/index.d.ts

@@ -1,3 +1,4 @@
 export declare function getToken(): Promise<string>;
-export declare function resetTokenCacheForTesting(): void;
+export declare function clearTokenCache(): void;
+export declare const resetTokenCacheForTesting: typeof clearTokenCache;
 //# 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,yBAAyB,IAAI,IAAI,CAGhD"}
+{"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;AAED,eAAO,MAAM,yBAAyB,wBAAkB,CAAC"}

package/dist/auth/index.js

@@ -37,7 +37,8 @@ export async function getToken() {
     }
     return inFlight;
 }
-export function resetTokenCacheForTesting() {
+export function clearTokenCache() {
     cached = null;
     inFlight = null;
 }
+export const resetTokenCacheForTesting = clearTokenCache;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { runMcp, type RunMcpOptions } from './runner.js';
-export { apiRequest } from './api-client.js';
-export { getToken } from './auth/index.js';
+export { apiRequest, UnauthorizedError } from './api-client.js';
+export { getToken, clearTokenCache } from './auth/index.js';
 export { runWithAuthContext, getRequestBearerToken } from './auth/context.js';
 export type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.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,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,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,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
 export { runMcp } from './runner.js';
-export { apiRequest } from './api-client.js';
-export { getToken } from './auth/index.js';
+export { apiRequest, UnauthorizedError } from './api-client.js';
+export { getToken, clearTokenCache } from './auth/index.js';
 export { runWithAuthContext, getRequestBearerToken } from './auth/context.js';

package/dist/transports/http.d.ts

@@ -4,6 +4,20 @@ export interface HttpServerOptions {
     host?: string;
     stateless?: boolean;
     createServer: () => McpServer;
+    /**
+     * URL of the OAuth 2.0 Authorization Server users authenticate against.
+     * Surfaced to MCP clients via /.well-known/oauth-protected-resource so
+     * they can drive the standard PKCE flow when no Bearer is present.
+     *
+     * Must be the host that serves the OIDC / OAuth 2.0 discovery metadata
+     * (i.e. `<host>/.well-known/openid-configuration` or
+     * `<host>/.well-known/oauth-authorization-server`). For FerrLabs that's
+     * `api.ferrlabs.com` — `auth.ferrlabs.com` is the user-facing login SPA
+     * but doesn't serve the metadata documents.
+     *
+     * Defaults to `FERRLABS_AUTH_URL` env or `https://api.ferrlabs.com`.
+     */
+    authorizationServer?: string;
 }
 export declare function startHttpServer(opts: HttpServerOptions): Promise<void>;
 //# sourceMappingURL=http.d.ts.map

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;AAUzE,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;CAC/B;AAoBD,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2E5E"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBzE,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;AAoBD,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuH5E"}

package/dist/transports/http.js

@@ -9,6 +9,11 @@ function extractBearer(req) {
     const match = /^Bearer\s+(.+)$/i.exec(header);
     return match?.[1];
 }
+function publicOrigin(req) {
+    const proto = req.headers['x-forwarded-proto']?.split(',')[0]?.trim() ?? 'https';
+    const host = req.headers['x-forwarded-host'] ?? req.headers.host ?? '';
+    return `${proto}://${host}`;
+}
 async function readJsonBody(req) {
     if (req.method !== 'POST')
         return undefined;
@@ -31,8 +36,40 @@ async function readJsonBody(req) {
 }
 export async function startHttpServer(opts) {
     const { port, host = '0.0.0.0', stateless = true } = opts;
+    const authServer = opts.authorizationServer ?? process.env.FERRLABS_AUTH_URL ?? 'https://api.ferrlabs.com';
     const transports = new Map();
+    function sendUnauthorized(req, res) {
+        const origin = publicOrigin(req);
+        const metadataUrl = `${origin}/.well-known/oauth-protected-resource`;
+        res.writeHead(401, {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': `Bearer resource_metadata="${metadataUrl}"`,
+        });
+        res.end(JSON.stringify({
+            jsonrpc: '2.0',
+            error: {
+                code: -32001,
+                message: 'Missing or invalid bearer token. The MCP client should fetch the OAuth protected-resource metadata and run the authorization code + PKCE flow.',
+            },
+            id: null,
+        }));
+    }
+    function sendResourceMetadata(req, res) {
+        const origin = publicOrigin(req);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            resource: origin,
+            authorization_servers: [authServer],
+            bearer_methods_supported: ['header'],
+            resource_documentation: 'https://ferrlabs.com',
+        }));
+    }
     async function handleMcpRequest(req, res) {
+        const bearerToken = extractBearer(req);
+        if (!bearerToken) {
+            sendUnauthorized(req, res);
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'] ?? undefined;
         let transport = sessionId ? transports.get(sessionId) : undefined;
         if (sessionId && !transport && !stateless) {
@@ -67,7 +104,6 @@ export async function startHttpServer(opts) {
             await server.connect(transport);
         }
         const body = await readJsonBody(req);
-        const bearerToken = extractBearer(req);
         await runWithAuthContext({ bearerToken }, () => transport.handleRequest(req, res, body));
     }
     const httpServer = createHttpServer((req, res) => {
@@ -77,6 +113,10 @@ export async function startHttpServer(opts) {
             res.end(JSON.stringify({ status: 'ok', service: 'ferrlabs-mcp' }));
             return;
         }
+        if (url === '/.well-known/oauth-protected-resource') {
+            sendResourceMetadata(req, res);
+            return;
+        }
         if (url === '/mcp' || url.startsWith('/mcp?')) {
             handleMcpRequest(req, res).catch((err) => {
                 if (!res.headersSent) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferrlabs/mcp-core",
-  "version": "6.1.0",
-  "description": "Shared core for FerrLabs MCP servers — auth, transports (stdio + Streamable HTTP), api-client, runner",
+  "version": "6.2.2",
+  "description": "Shared core for FerrLabs MCP servers — auth, transports (stdio + Streamable HTTP), api-client, runner",
   "license": "MPL-2.0",
   "type": "module",
   "main": "./dist/index.js",