@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/mcp/__tests__/downstream-token-refresh.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { DownstreamRefreshGuard, isDownstreamTokenRejection } from '../downstream-token-refresh.js';
+
+describe('isDownstreamTokenRejection', () => {
+  it('reads a failed call: the SDK error carries the HTTP status', () => {
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(401, 'Error POSTing to endpoint: '))).toBe(true);
+  });
+
+  it('reads a failed registration: @utcp/mcp flattens it to prose with only the body left', () => {
+    expect(
+      isDownstreamTokenRejection(
+        new Error(`Server 'srv': Streamable HTTP error: Error POSTing to endpoint: {"error":"invalid_token"}`),
+      ),
+    ).toBe(true);
+    expect(isDownstreamTokenRejection('HTTP 401 Unauthorized')).toBe(true);
+  });
+
+  it('follows the cause chain', () => {
+    expect(isDownstreamTokenRejection(new Error('tool failed', { cause: { status: 401 } }))).toBe(true);
+  });
+
+  it('is not fooled by anything that is not a token rejection', () => {
+    // 403: the token is fine, it just is not permitted — a refresh changes nothing.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(403, 'Forbidden'))).toBe(false);
+    // Session loss, a JSON-RPC code, an ordinary tool failure.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(404, '{"code":-32001,"message":"Session not found"}'))).toBe(false);
+    expect(isDownstreamTokenRejection(new McpError(ErrorCode.RequestTimeout, 'Request timed out'))).toBe(false);
+    expect(isDownstreamTokenRejection(new Error('kaboom'))).toBe(false);
+    // Digits inside a URL are not a status.
+    expect(isDownstreamTokenRejection(new Error('connect ECONNREFUSED https://api.example.com/v1/401/x'))).toBe(false);
+  });
+
+  it('a stated non-401 status outranks its own prose', () => {
+    // Providers do answer 403 with an OAuth error body. The status is the
+    // verdict — refreshing would swap a valid token for another equally
+    // unpermitted one, once a minute, forever.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(403, '{"error":"invalid_token"}'))).toBe(false);
+    expect(isDownstreamTokenRejection({ status: 403, message: 'Unauthorized' })).toBe(false);
+    expect(isDownstreamTokenRejection({ response: { status: 500 }, message: 'invalid_token' })).toBe(false);
+    // …and a 403 shell does not let its own body be re-read one link up.
+    expect(
+      isDownstreamTokenRejection(new Error('call failed', { cause: { status: 403, message: 'invalid_token' } })),
+    ).toBe(false);
+    // A status is still only a number in the HTTP range: `code` as a syscall
+    // name or a JSON-RPC code leaves the status unknown, so the message decides.
+    expect(isDownstreamTokenRejection({ code: 'ECONNRESET', message: 'invalid_token' })).toBe(true);
+    expect(isDownstreamTokenRejection({ code: -32000, message: 'invalid_token' })).toBe(true);
+  });
+
+  it('reads "unauthorized" as a word, not as the start of some other OAuth error', () => {
+    // `unauthorized_client` is about the client registration; a refreshed
+    // token changes nothing about it, so it must not cost a refresh (or, for
+    // a grant with no refresh token, the sign-in).
+    expect(
+      isDownstreamTokenRejection(new Error(`Server 'srv': Streamable HTTP error: Error POSTing to endpoint: {"error":"unauthorized_client"}`)),
+    ).toBe(false);
+    expect(isDownstreamTokenRejection(new Error('Error POSTing to endpoint: {"error":"unauthorized"}'))).toBe(true);
+  });
+});
+
+describe('DownstreamRefreshGuard — at most once per (user, manual) per minute', () => {
+  it('refuses a second refresh inside the window and allows one after it', async () => {
+    let now = 0;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    const refresh = async () => `run-${++runs}`;
+
+    await expect(guard.run('u\0notion', refresh)).resolves.toBe('run-1');
+    now += 59_999;
+    expect(guard.run('u\0notion', refresh)).toBeUndefined();
+    // Another (user, manual) pair has a window of its own.
+    await expect(guard.run('u\0linear', refresh)).resolves.toBe('run-2');
+    now += 1;
+    await expect(guard.run('u\0notion', refresh)).resolves.toBe('run-3');
+    expect(runs).toBe(3);
+  });
+
+  it('a rejection that arrives while the refresh runs shares its outcome instead of being refused', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    let release!: (v: string) => void;
+    let runs = 0;
+    const refresh = () => {
+      runs += 1;
+      return new Promise<string>((r) => (release = r));
+    };
+    const first = guard.run('k', refresh);
+    const second = guard.run('k', refresh);
+    expect(second).toBeDefined();
+    release('refreshed');
+    await expect(Promise.all([first, second])).resolves.toEqual(['refreshed', 'refreshed']);
+    expect(runs).toBe(1);
+    // Settled, still inside the window: no more.
+    expect(guard.run('k', refresh)).toBeUndefined();
+  });
+
+  it('a refresh that never settles does not pin its key past the window', async () => {
+    let now = 0;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    // A token request with no timeout, hanging forever.
+    const hang = () => {
+      runs += 1;
+      return new Promise<string>(() => {});
+    };
+    expect(guard.run('k', hang)).toBeDefined();
+    now += 59_999;
+    expect(guard.run('k', hang)).toBeDefined(); // still in flight — shared, not re-run
+    expect(runs).toBe(1);
+    now += 1;
+    // The window is over. The hung attempt is forgotten rather than holding
+    // this key — and this map entry — for the life of the process.
+    await expect(guard.run('k', async () => 'recovered')).resolves.toBe('recovered');
+    expect(runs).toBe(1);
+  });
+
+  it('a clock that steps backward does not stretch the window by the step', async () => {
+    let now = 1_000_000;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    const refresh = async () => `run-${++runs}`;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-1');
+
+    // An NTP step of ten minutes into the past. Measured from the old stamp
+    // this window would now hold for eleven minutes, not one.
+    now -= 600_000;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-2');
+    // …and from there the usual minute applies.
+    now += 59_999;
+    expect(guard.run('k', refresh)).toBeUndefined();
+    now += 1;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-3');
+  });
+
+  it('clearWhere forgets the windows it selects, by key and by outcome', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    await guard.run('u1\0notion', async () => 'transient');
+    await guard.run('u1\0linear', async () => 'refreshed');
+    await guard.run('u2\0notion', async () => 'transient');
+
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== 'refreshed');
+
+    // Forgotten: u1's failed window. Kept: u1's successful one, and u2 entirely.
+    await expect(guard.run('u1\0notion', async () => 'again')).resolves.toBe('again');
+    expect(guard.run('u1\0linear', async () => 'again')).toBeUndefined();
+    expect(guard.run('u2\0notion', async () => 'again')).toBeUndefined();
+  });
+
+  it('a refresh still in flight is not cleared by the predicate the proxy uses', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    let runs = 0;
+    let release!: (v: string) => void;
+    const refresh = () => {
+      runs += 1;
+      return new Promise<string>((r) => (release = r));
+    };
+    const first = guard.run('u1\0notion', refresh);
+
+    // Exactly what `forgetStaleRefreshWindows` passes. A refresh of our own is
+    // itself a secrets mutation, and it notifies BEFORE it settles — so an
+    // in-flight window (outcome still undefined) must survive this, or the
+    // guard would be reset by the very refresh it issued and a provider that
+    // keeps minting refused tokens would get one refresh per call.
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== undefined && outcome !== 'refreshed');
+
+    // Still the same attempt: shared, not re-run, and not refused either.
+    const second = guard.run('u1\0notion', refresh);
+    expect(second).toBeDefined();
+    release('refreshed');
+    await expect(Promise.all([first, second])).resolves.toEqual(['refreshed', 'refreshed']);
+    expect(runs).toBe(1);
+    // And once it HAS settled as 'refreshed', the window still stands.
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== undefined && outcome !== 'refreshed');
+    expect(guard.run('u1\0notion', refresh)).toBeUndefined();
+    expect(runs).toBe(1);
+  });
+});

package/src/modules/mcp/__tests__/fake-downstream-mcp-server.ts

@@ -0,0 +1,156 @@
+import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  isInitializeRequest,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * A SESSION-FUL third-party MCP server over real HTTP — the kind an `mcp.json`
+ * manual points at — for driving the proxy's downstream pool.
+ *
+ * Real, not stubbed, for the same reason as mcp-core's recovery fixture: the
+ * pool's healing rests on a live server's session-loss shape (404 / `-32001`)
+ * travelling intact through the SDK transport and `@utcp/mcp`.
+ *
+ * Not collected by vitest: the include pattern is `**\/*.test.ts`.
+ */
+export interface FakeDownstreamMcpServer {
+  url: string;
+  /** Forget every session, as a restart does. The process stays up. */
+  restart(): Promise<void>;
+  /** Stop listening and drop every connection. */
+  stop(): Promise<void>;
+  /** `initialize` requests served — one per downstream connection that reached the server. */
+  initializations(): number;
+  /** Times `echo` actually executed. */
+  executions(): number;
+  /** Sessions currently live on the server. */
+  liveSessions(): number;
+  /** Requests answered 401 because `acceptsToken` refused their bearer. */
+  rejections(): number;
+}
+
+export interface FakeDownstreamOptions {
+  /**
+   * When set, every request must carry `Authorization: Bearer <token>` with a
+   * token this accepts; anything else is answered 401 with an RFC 6750
+   * `invalid_token` challenge — what an OAuth-protected MCP server answers a
+   * revoked or expired token with.
+   */
+  acceptsToken?: (token: string) => boolean;
+}
+
+export async function startFakeDownstreamMcpServer(opts: FakeDownstreamOptions = {}): Promise<FakeDownstreamMcpServer> {
+  const sessions = new Map<string, StreamableHTTPServerTransport>();
+  let initializations = 0;
+  let executions = 0;
+  let rejections = 0;
+
+  function buildServer(): Server {
+    const server = new Server({ name: 'downstream', version: '0.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'echo',
+          description: 'Return the text it was given.',
+          inputSchema: { type: 'object' as const, properties: { text: { type: 'string' } } },
+        },
+      ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+      executions += 1;
+      const text = String((request.params.arguments as { text?: unknown } | undefined)?.text ?? '');
+      return { content: [{ type: 'text', text: JSON.stringify({ echoed: text }) }] };
+    });
+    return server;
+  }
+
+  function jsonRpcError(res: ServerResponse, status: number, code: number, message: string): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+  }
+
+  async function readBody(req: IncomingMessage): Promise<unknown> {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(chunk as Buffer);
+    if (chunks.length === 0) return undefined;
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch {
+      return undefined;
+    }
+  }
+
+  const http: HttpServer = createServer((req, res) => {
+    void (async () => {
+      if (opts.acceptsToken) {
+        const token = String(req.headers.authorization ?? '').replace(/^Bearer\s+/i, '');
+        if (!opts.acceptsToken(token)) {
+          rejections += 1;
+          res.writeHead(401, {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': 'Bearer error="invalid_token", error_description="The access token is invalid"',
+          });
+          res.end(JSON.stringify({ error: 'invalid_token', error_description: 'The access token is invalid' }));
+          return;
+        }
+      }
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+      const body = req.method === 'POST' ? await readBody(req) : undefined;
+      const live = sessionId ? sessions.get(sessionId) : undefined;
+      if (live) {
+        await live.handleRequest(req, res, body);
+        return;
+      }
+      if (req.method === 'POST' && isInitializeRequest(body)) {
+        initializations += 1;
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (id: string) => {
+            sessions.set(id, transport);
+          },
+        });
+        await buildServer().connect(transport);
+        await transport.handleRequest(req, res, body);
+        return;
+      }
+      if (sessionId) {
+        jsonRpcError(res, 404, -32001, 'Session not found');
+        return;
+      }
+      jsonRpcError(res, 400, -32000, 'Bad Request: Mcp-Session-Id header is required');
+    })().catch(() => {
+      if (!res.headersSent) jsonRpcError(res, 500, -32603, 'Internal error');
+      else res.end();
+    });
+  });
+
+  await new Promise<void>((resolve) => http.listen(0, '127.0.0.1', resolve));
+  const { port } = http.address() as AddressInfo;
+
+  async function dropSessions(): Promise<void> {
+    const live = [...sessions.values()];
+    sessions.clear();
+    await Promise.all(live.map((t) => t.close().catch(() => {})));
+  }
+
+  return {
+    url: `http://127.0.0.1:${port}/mcp`,
+    restart: dropSessions,
+    async stop() {
+      await dropSessions();
+      http.closeAllConnections();
+      await new Promise<void>((resolve) => http.close(() => resolve()));
+    },
+    initializations: () => initializations,
+    executions: () => executions,
+    liveSessions: () => sessions.size,
+    rejections: () => rejections,
+  };
+}

package/src/modules/mcp/__tests__/first-call-probe.cli-args.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { ConfigError, count, FLAG_NAMES, parseArgs, parseCliRequest, USAGE } from '../first-call-probe.cli-args.js';
+
+/**
+ * What the probe CLI does with the words it is given.
+ *
+ * Two things are pinned here. First, that a flag the probe cannot honour is
+ * REFUSED rather than reinterpreted: `--concurrency 0` would otherwise reach
+ * `runPooled`'s `Math.max(1, …)` and produce a one-at-a-time run reported as
+ * the fifty-wide burst that was asked for — a wrong number in a ticket log is
+ * worse than no number. Second, that a flag value cannot forge the output: the
+ * refusal is printed straight to a terminal or a CI log, and the value quoted
+ * in it came from whoever typed the command.
+ */
+const REQUIRED = ['--base-url', 'https://core-staging.bevel.software', '--bearer', 'bevel_k'];
+const env = {} as NodeJS.ProcessEnv;
+
+/** The message alone — every refusal here is the message, not the stack. */
+function refusal(run: () => unknown): string {
+  try {
+    run();
+  } catch (err) {
+    return (err as Error).message;
+  }
+  throw new Error('expected a refusal, got none');
+}
+
+describe('parseArgs', () => {
+  it('reads `--flag value` pairs and bare `--flag` switches', () => {
+    expect(parseArgs(['--base-url', 'http://x', '--json', '--connections', '5'])).toEqual({
+      'base-url': 'http://x',
+      json: 'true',
+      connections: '5',
+    });
+  });
+
+  it('skips the conventional end-of-options separator, which some runners pass through', () => {
+    // The documented invocation is `pnpm … probe:first-call -- --base-url …`.
+    // pnpm normally eats the `--`; a runner that does not must not turn the
+    // documented command into an error.
+    expect(parseArgs(['--', '--tool', 'start_session'])).toEqual({ tool: 'start_session' });
+  });
+
+  it('refuses a mistyped flag instead of running the default probe behind it', () => {
+    // The failure this prevents: `--concurency 1` was dropped and the default
+    // fifty-wide burst ran, reported as the one-at-a-time run that was asked
+    // for. A probe run is evidence, so a wrong number that looks right is the
+    // worst thing it can produce.
+    expect(refusal(() => parseArgs(['--base-url', 'http://x', '--concurency', '1']))).toBe(
+      'unknown option "--concurency"',
+    );
+    expect(() => parseArgs(['--concurency', '1'])).toThrow(ConfigError);
+  });
+
+  it('refuses a stray word that belongs to no flag', () => {
+    expect(refusal(() => parseArgs(['junk', '--tool', 'start_session']))).toMatch(/unexpected argument "junk"/);
+  });
+
+  it('refuses a value flag left without its value, rather than inventing one', () => {
+    // `--bearer` with nothing after it became the literal bearer `"true"`: every
+    // attempt came back 401 and the report read as fifty platform failures —
+    // a reproduction of a bug that was never there.
+    expect(refusal(() => parseArgs(['--base-url', 'http://x', '--bearer']))).toBe('--bearer needs a value');
+    expect(refusal(() => parseArgs(['--bearer', '--json']))).toBe('--bearer needs a value');
+    expect(refusal(() => parseArgs(['--tool']))).toBe('--tool needs a value');
+  });
+
+  it('lets a switch stand next to another flag without eating it', () => {
+    expect(parseArgs(['--json', '--tool', 'ask'])).toEqual({ json: 'true', tool: 'ask' });
+  });
+
+  it('takes a negative value, leaving the range to the flag that owns it', () => {
+    // `-5` is not `--something`, so it is this flag's value; `count` is what
+    // says it is out of range, and it names the flag when it does.
+    expect(parseArgs(['--timeout', '-5'])).toEqual({ timeout: '-5' });
+  });
+
+  it('escapes what it quotes back, so a mistyped flag cannot forge a log line', () => {
+    const message = refusal(() => parseArgs(['--x\n  50/50 succeeded, 0 failed']));
+
+    expect(message.split('\n')).toHaveLength(1);
+    expect(message).toContain('\\n');
+  });
+
+  it('documents every flag it accepts', () => {
+    // The table and the usage text are two lists of the same thing, and a flag
+    // that exists but is undocumented is as good as absent to an operator.
+    for (const name of FLAG_NAMES) {
+      if (name === 'h') continue; // the one alias, deliberately not advertised
+      expect(USAGE).toContain(`--${name}`);
+    }
+  });
+});
+
+describe('count', () => {
+  it('leaves an absent flag undefined, so the probe keeps its own default', () => {
+    expect(count({}, 'connections')).toBeUndefined();
+  });
+
+  it('accepts a positive integer', () => {
+    expect(count({ connections: '50' }, 'connections')).toBe(50);
+  });
+
+  it.each(['0', '-5', '1.5', 'abc', '', 'Infinity', 'NaN'])('refuses %o rather than running something else', (raw) => {
+    expect(() => count({ concurrency: raw }, 'concurrency')).toThrow(ConfigError);
+    expect(refusal(() => count({ concurrency: raw }, 'concurrency'))).toMatch(
+      /--concurrency must be a positive integer/,
+    );
+  });
+
+  it('escapes the value it quotes back, so a flag cannot forge a log line', () => {
+    // The message goes to stderr as-is. Unescaped, this value would print a
+    // second line reading like a result the probe produced, and the escape
+    // sequence would recolour everything after it.
+    const message = refusal(() => count({ connections: 'x\n  50/50 succeeded, 0 failed' }, 'connections'));
+
+    expect(message.split('\n')).toHaveLength(1);
+    expect(message).not.toContain('');
+    // Escaped, not dropped: the operator still sees exactly what they typed.
+    expect(message).toContain('\\n');
+    expect(message).toContain('\\u001b[31m');
+  });
+});
+
+describe('parseCliRequest', () => {
+  it('asks for the usage text and nothing else', () => {
+    expect(parseCliRequest(['--help'], env)).toEqual({ help: true });
+    expect(parseCliRequest(['--h'], env)).toEqual({ help: true });
+    expect(USAGE).toContain('--base-url');
+  });
+
+  it('turns the flags into the probe options, defaults left to the probe', () => {
+    const request = parseCliRequest([...REQUIRED, '--connections', '50', '--mode', 'tool', '--json'], env);
+
+    expect(request).toEqual({
+      help: false,
+      json: true,
+      options: {
+        baseUrl: 'https://core-staging.bevel.software',
+        bearer: 'bevel_k',
+        mode: 'tool',
+        connections: 50,
+        // Not defaulted here: `probeFirstCall` owns what absent means, so the
+        // CLI and a programmatic caller cannot drift apart.
+        concurrency: undefined,
+        timeoutMs: undefined,
+        toolName: undefined,
+      },
+    });
+  });
+
+  it('takes the bearer from the environment, so a key need not enter shell history', () => {
+    const request = parseCliRequest(['--base-url', 'http://x'], { PROBE_BEARER: 'from-env' } as NodeJS.ProcessEnv);
+
+    expect(request).toMatchObject({ help: false, options: { bearer: 'from-env' } });
+  });
+
+  it('names the one that is missing', () => {
+    expect(refusal(() => parseCliRequest(['--bearer', 'k'], env))).toMatch(/--base-url is required/);
+    expect(refusal(() => parseCliRequest(['--base-url', 'http://x'], env))).toMatch(
+      /--bearer \(or \$PROBE_BEARER\) is required/,
+    );
+  });
+
+  it('refuses a mode it does not have, with the value escaped', () => {
+    expect(refusal(() => parseCliRequest([...REQUIRED, '--mode', 'grpc'], env))).toBe(
+      '--mode must be mcp or tool, got "grpc"',
+    );
+    expect(refusal(() => parseCliRequest([...REQUIRED, '--mode', 'grpc\nFAKE'], env)).split('\n')).toHaveLength(1);
+  });
+
+  it('refuses a bad count before the probe is ever constructed', () => {
+    expect(() => parseCliRequest([...REQUIRED, '--concurrency', '0'], env)).toThrow(ConfigError);
+    expect(refusal(() => parseCliRequest([...REQUIRED, '--timeout', '-1'], env))).toMatch(
+      /--timeout must be a positive integer/,
+    );
+  });
+});