@mcpfn/testing 0.0.1 → 0.0.3

package/dist/index.js

@@ -404,6 +404,28 @@ var MCPFN_OAUTH_EXTENSION_GRANTS = {
   deviceCode: "urn:ietf:params:oauth:grant-type:device_code",
   generic: "urn:example:params:oauth:grant-type:extension"
 };
+var MCPFN_NAMED_OAUTH_HOST_FIXTURES = {
+  chatgpt: {
+    id: "chatgpt",
+    name: "ChatGPT connector",
+    redirectUris: ["https://chatgpt.com/connector_platform_oauth_redirect"],
+    responseTypes: ["code"],
+    grantTypes: ["authorization_code", "refresh_token"],
+    tokenEndpointAuthMethod: "none"
+  },
+  claude: {
+    id: "claude",
+    name: "Claude connector",
+    redirectUris: ["https://claude.example.com/oauth/callback"],
+    responseTypes: ["code"],
+    grantTypes: [
+      "authorization_code",
+      "refresh_token",
+      MCPFN_OAUTH_EXTENSION_GRANTS.jwtBearer
+    ],
+    tokenEndpointAuthMethod: "none"
+  }
+};
 function createOAuthClientMetadataFixture(options) {
   return {
     ...options.extraMetadata,
@@ -451,17 +473,15 @@ function assertAuthorizationCodeClientMetadata(metadata, expectedClientId) {
 }
 
 // src/mock-oauth-server.ts
-import { createHash, randomBytes, randomUUID } from "crypto";
+import { randomUUID } from "crypto";
 import { createServer } from "http";
-function base64Url(value) {
-  return value.toString("base64url");
-}
+import { derivePkceS256Challenge, generatePkcePair } from "@superfunctions/oauth-core";
 function createPkcePair() {
-  const verifier = base64Url(randomBytes(48));
+  const pair = generatePkcePair(48);
   return {
-    verifier,
-    challenge: createHash("sha256").update(verifier).digest("base64url"),
-    method: "S256"
+    verifier: pair.codeVerifier,
+    challenge: pair.codeChallenge,
+    method: pair.codeChallengeMethod
   };
 }
 function uniqueScopes(value) {
@@ -586,7 +606,8 @@ var McpFnMockOAuthAuthorizationServer = class {
         grant_types_supported: ["authorization_code", "refresh_token"],
         code_challenge_methods_supported: ["S256"],
         token_endpoint_auth_methods_supported: ["none"],
-        scopes_supported: this.scopesSupported
+        scopes_supported: this.scopesSupported,
+        client_id_metadata_document_supported: true
       });
     }
     if (request.method === "GET" && path2.startsWith("/client-metadata/")) {
@@ -698,7 +719,7 @@ var McpFnMockOAuthAuthorizationServer = class {
       return oauthError(400, "invalid_grant", "Authorization code binding does not match");
     }
     const verifier = formValue(form, "code_verifier");
-    const challenge = verifier ? createHash("sha256").update(verifier).digest("base64url") : void 0;
+    const challenge = verifier ? derivePkceS256Challenge(verifier) : void 0;
     if (challenge !== record.codeChallenge) {
       return oauthError(400, "invalid_grant", "PKCE verification failed");
     }
@@ -779,7 +800,9 @@ async function startMockOAuthAuthorizationServer(options = {}) {
   const server = createServer(async (req, res) => {
     try {
       if (!oauth) throw new Error("Mock OAuth server is not initialized");
-      await writeResponse(res, await oauth.handle(await toRequest(req, origin)));
+      const request = await toRequest(req, origin);
+      const custom = await options.handle?.(request.clone(), oauth);
+      await writeResponse(res, custom ?? await oauth.handle(request));
     } catch {
       res.statusCode = 500;
       res.setHeader("content-type", "application/json");
@@ -809,123 +832,210 @@ async function startMockOAuthAuthorizationServer(options = {}) {
 }
 
 // src/client.ts
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import {
-  CallToolResultSchema,
-  CreateTaskResultSchema
-} from "@modelcontextprotocol/sdk/types.js";
+  createMcpFnClient,
+  customTarget
+} from "@mcpfn/client";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 var McpFnTestClient = class _McpFnTestClient {
-  client;
-  server;
-  closed = false;
-  constructor(client, server) {
-    this.client = client;
-    this.server = server;
+  session;
+  constructor(session) {
+    this.session = session;
+  }
+  get client() {
+    return this.session.protocol;
   }
   static async connect(server, info = { name: "mcpfn-test-client", version: "1.0.0" }, options = {}) {
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    const client = new Client(info, { capabilities: options.capabilities ?? {} });
-    await options.configure?.(client);
-    await server.connect(serverTransport);
-    await client.connect(clientTransport);
-    return new _McpFnTestClient(client, server);
-  }
-  async listTools() {
-    const values = [];
-    let cursor;
-    do {
-      const page = await this.client.listTools(cursor ? { cursor } : void 0);
-      values.push(...page.tools);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return values;
-  }
-  async callTool(name, args = {}) {
-    return await this.client.callTool({ name, arguments: args });
-  }
-  async createToolTask(name, args = {}, options = {}) {
-    return this.client.request(
-      {
-        method: "tools/call",
-        params: { name, arguments: args, task: options }
-      },
-      CreateTaskResultSchema
-    );
+    const serverName = server.info?.name ?? "mcpfn-server";
+    return this.connectTarget(customTarget({
+      kind: "in-memory",
+      descriptor: { server: serverName },
+      open: async () => {
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        return { transport: clientTransport, close: () => server.close() };
+      }
+    }), info, options);
+  }
+  static async connectTarget(target, info, options = {}) {
+    const session = createMcpFnClient({
+      target,
+      info: info ?? { name: "mcpfn-test-client", version: "1.0.0" },
+      capabilities: options.capabilities,
+      handlers: options.handlers,
+      events: options.events,
+      configure: options.configure,
+      diagnostics: options.diagnostics
+    });
+    try {
+      await session.connect();
+      return new _McpFnTestClient(session);
+    } catch (error) {
+      await session.close(true).catch(() => void 0);
+      throw error;
+    }
   }
-  getTask(taskId) {
-    return this.client.experimental.tasks.getTask(taskId);
+  listTools(options) {
+    return this.session.tools.listAll(options);
   }
-  getTaskResult(taskId) {
-    return this.client.experimental.tasks.getTaskResult(
-      taskId,
-      CallToolResultSchema
-    );
+  callTool(name, args = {}, options) {
+    return this.session.tools.call(name, args, options);
+  }
+  createToolTask(name, args = {}, task = {}, options) {
+    return this.session.tools.createTask(name, args, task, options);
+  }
+  getTask(taskId, options) {
+    return this.session.tasks.get(taskId, options);
+  }
+  getTaskResult(taskId, options) {
+    return this.session.tasks.result(taskId, options);
+  }
+  listTasks(cursor, options) {
+    return this.session.tasks.list(cursor, options);
+  }
+  cancelTask(taskId, options) {
+    return this.session.tasks.cancel(taskId, options);
+  }
+  listResources(options) {
+    return this.session.resources.listAll(options);
+  }
+  listResourceTemplates(options) {
+    return this.session.resources.listTemplatesAll(options);
+  }
+  readResource(uri, options) {
+    return this.session.resources.read(uri, options);
+  }
+  subscribeResource(uri, options) {
+    return this.session.resources.subscribe(uri, options);
+  }
+  unsubscribeResource(uri, options) {
+    return this.session.resources.unsubscribe(uri, options);
+  }
+  listPrompts(options) {
+    return this.session.prompts.listAll(options);
+  }
+  getPrompt(name, args, options) {
+    return this.session.prompts.get(name, args, options);
   }
-  listTasks(cursor) {
-    return this.client.experimental.tasks.listTasks(cursor);
-  }
-  cancelTask(taskId) {
-    return this.client.experimental.tasks.cancelTask(taskId);
-  }
-  async listResources() {
-    const values = [];
-    let cursor;
-    do {
-      const page = await this.client.listResources(cursor ? { cursor } : void 0);
-      values.push(...page.resources);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return values;
-  }
-  async listResourceTemplates() {
-    const values = [];
-    let cursor;
-    do {
-      const page = await this.client.listResourceTemplates(cursor ? { cursor } : void 0);
-      values.push(...page.resourceTemplates);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return values;
-  }
-  readResource(uri) {
-    return this.client.readResource({ uri });
-  }
-  async subscribeResource(uri) {
-    await this.client.subscribeResource({ uri });
-  }
-  async unsubscribeResource(uri) {
-    await this.client.unsubscribeResource({ uri });
-  }
-  async listPrompts() {
-    const values = [];
-    let cursor;
-    do {
-      const page = await this.client.listPrompts(cursor ? { cursor } : void 0);
-      values.push(...page.prompts);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return values;
-  }
-  getPrompt(name, args) {
-    return this.client.getPrompt({ name, ...args ? { arguments: args } : {} });
-  }
-  complete(params) {
-    return this.client.complete(params);
-  }
-  async close() {
-    if (this.closed) return;
-    this.closed = true;
-    await this.client.close().catch(() => void 0);
-    await this.server.close().catch(() => void 0);
+  complete(params, options) {
+    return this.session.prompts.complete(params, options);
+  }
+  close() {
+    return this.session.close();
   }
 };
 
 // src/conformance.ts
 import { spawn } from "child_process";
 import { existsSync } from "fs";
+import {
+  createServer as createServer2,
+  request as httpRequest
+} from "http";
+import { request as httpsRequest } from "https";
 import path from "path";
 var OFFICIAL_CONFORMANCE_VERSION = "0.1.16";
+async function createAuthenticatedConformanceProxy(options) {
+  const upstream = new URL(options.url);
+  if (!["http:", "https:"].includes(upstream.protocol)) {
+    throw new TypeError(
+      "Authenticated conformance upstream must use HTTP or HTTPS"
+    );
+  }
+  if (upstream.username || upstream.password || upstream.hash) {
+    throw new TypeError(
+      "Authenticated conformance upstream must not contain userinfo or a fragment"
+    );
+  }
+  const hostname = normalizeLoopbackHostname(upstream.hostname);
+  if (!hostname) {
+    throw new TypeError(
+      "Authenticated conformance upstream must use a literal loopback address"
+    );
+  }
+  const protocol = upstream.protocol === "https:" ? "https:" : "http:";
+  const port = upstream.port === "" ? void 0 : Number(upstream.port);
+  const requestPath = `${upstream.pathname}${upstream.search}`;
+  const injected = new Headers(options.headers);
+  const activeRequests = /* @__PURE__ */ new Set();
+  const activeSockets = /* @__PURE__ */ new Set();
+  let proxyAuthority;
+  const server = createServer2((incoming, outgoing) => {
+    if (!incoming.url?.startsWith("/")) {
+      outgoing.writeHead(400).end();
+      return;
+    }
+    const headers = { ...incoming.headers };
+    delete headers.connection;
+    const usesProxyAuthority = incoming.headers.host === proxyAuthority;
+    injected.forEach((value, name) => {
+      const normalizedName = name.toLowerCase();
+      delete headers[normalizedName];
+      if (usesProxyAuthority) headers[normalizedName] = value;
+    });
+    if (usesProxyAuthority) headers.host = upstream.host;
+    const transport = protocol === "https:" ? httpsRequest : httpRequest;
+    const proxied = transport(
+      {
+        protocol,
+        hostname,
+        port,
+        path: requestPath,
+        method: incoming.method,
+        headers
+      },
+      (response) => {
+        outgoing.writeHead(response.statusCode ?? 502, response.headers);
+        response.pipe(outgoing);
+      }
+    );
+    activeRequests.add(proxied);
+    proxied.once("close", () => activeRequests.delete(proxied));
+    proxied.once("error", () => {
+      if (!outgoing.headersSent) outgoing.writeHead(502);
+      outgoing.end();
+    });
+    incoming.once("aborted", () => proxied.destroy());
+    incoming.pipe(proxied);
+  });
+  server.on("connection", (socket) => {
+    activeSockets.add(socket);
+    socket.once("close", () => activeSockets.delete(socket));
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw new Error("Authenticated conformance proxy did not bind a TCP port");
+  }
+  const url = new URL(
+    upstream.pathname + upstream.search,
+    `http://127.0.0.1:${address.port}`
+  );
+  proxyAuthority = url.host;
+  return {
+    url: url.toString(),
+    close: async () => {
+      for (const request of activeRequests) request.destroy();
+      for (const socket of activeSockets) socket.destroy();
+      if (!server.listening) return;
+      await new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+      });
+    }
+  };
+}
+function normalizeLoopbackHostname(hostname) {
+  if (hostname === "127.0.0.1") return "127.0.0.1";
+  if (hostname === "[::1]") return "::1";
+  return void 0;
+}
 function npxInvocation(args) {
   if (process.platform !== "win32") return { command: "npx", args };
   const npmExecPath = process.env.npm_execpath;
@@ -990,6 +1100,18 @@ async function runOfficialConformance(options) {
     });
   });
 }
+async function runAuthenticatedOfficialConformance(options) {
+  const { headers, ...conformance } = options;
+  const proxy = await createAuthenticatedConformanceProxy({
+    url: conformance.url,
+    headers
+  });
+  try {
+    return await runOfficialConformance({ ...conformance, url: proxy.url });
+  } finally {
+    await proxy.close();
+  }
+}
 
 // src/host-profiles.ts
 import {
@@ -1089,59 +1211,733 @@ function checkHostCompatibility(manifest, profile) {
       }
     }
   }
-  issues.sort((left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code));
-  const status = issues.some((issue) => issue.severity === "incompatible") ? "incompatible" : issues.length ? "degraded" : "compatible";
+  issues.sort((left, right) => {
+    if (left.path !== right.path) return left.path < right.path ? -1 : 1;
+    if (left.code < right.code) return -1;
+    if (left.code > right.code) return 1;
+    return 0;
+  });
+  let status = "compatible";
+  if (issues.some((issue) => issue.severity === "incompatible")) {
+    status = "incompatible";
+  } else if (issues.length > 0) {
+    status = "degraded";
+  }
   return { status, compatible: status !== "incompatible", issues };
 }
 
 // src/scenarios.ts
-async function runScenarios(client, scenarios) {
+import { redactOAuthValue } from "@superfunctions/oauth-core";
+function createMcpFnScenario(name, operation, result) {
+  switch (operation.kind) {
+    case "tools.call":
+      return createToolCallScenario(name, operation, result);
+    case "tools.call:task":
+      return createToolTaskScenario(name, operation);
+    case "resources.read":
+      return createResourceReadScenario(name, operation, result);
+    case "resources.subscribe":
+    case "resources.unsubscribe":
+      return createResourceLifecycleScenario(name, operation);
+    case "tasks.get":
+    case "tasks.cancel":
+      return createTaskLifecycleScenario(name, operation);
+    case "tasks.result":
+      return createTaskResultScenario(name, operation, result);
+    case "tasks.list":
+      return createTaskListScenario(name, operation);
+    case "prompts.get":
+      return createPromptScenario(name, operation, result);
+  }
+}
+function scenarioBase(name, sideEffect) {
+  return { formatVersion: 1, name, sideEffect };
+}
+function createToolCallScenario(name, operation, result) {
+  return {
+    ...scenarioBase(name, "non-idempotent"),
+    kind: "tools.call",
+    tool: operation.name,
+    ...operation.arguments ? { arguments: operation.arguments } : {},
+    expect: {
+      isError: Boolean(result.isError),
+      ...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+    }
+  };
+}
+function createToolTaskScenario(name, operation) {
+  return {
+    ...scenarioBase(name, "non-idempotent"),
+    kind: operation.kind,
+    tool: operation.name,
+    ...operation.arguments ? { arguments: operation.arguments } : {},
+    ...operation.task ? { task: operation.task } : {}
+  };
+}
+function createResourceReadScenario(name, operation, result) {
+  return {
+    ...scenarioBase(name, "none"),
+    kind: operation.kind,
+    uri: operation.uri,
+    expect: result
+  };
+}
+function createResourceLifecycleScenario(name, operation) {
+  return {
+    ...scenarioBase(name, "idempotent"),
+    kind: operation.kind,
+    uri: operation.uri
+  };
+}
+function createTaskLifecycleScenario(name, operation) {
+  return {
+    ...scenarioBase(name, operation.kind === "tasks.cancel" ? "idempotent" : "none"),
+    kind: operation.kind,
+    taskId: operation.taskId
+  };
+}
+function createTaskResultScenario(name, operation, result) {
+  return {
+    ...scenarioBase(name, "none"),
+    kind: operation.kind,
+    taskId: operation.taskId,
+    expect: result
+  };
+}
+function createTaskListScenario(name, operation) {
+  return {
+    ...scenarioBase(name, "none"),
+    kind: operation.kind,
+    ...operation.cursor ? { cursor: operation.cursor } : {}
+  };
+}
+function createPromptScenario(name, operation, result) {
+  return {
+    ...scenarioBase(name, "none"),
+    kind: operation.kind,
+    prompt: operation.name,
+    ...operation.arguments ? { arguments: operation.arguments } : {},
+    expect: result
+  };
+}
+function validateMcpFnScenarios(value) {
+  const artifact = isScenarioArtifact(value) ? value : void 0;
+  if (artifact?.status === "incomplete") {
+    throw new Error(`McpFn scenario artifact is incomplete: ${artifact.incompleteReason}`);
+  }
+  const scenarios = artifact?.scenarios ?? value;
+  if (!Array.isArray(scenarios)) {
+    throw new TypeError("Scenario module must export an array or mcpfn.scenarios artifact");
+  }
+  for (const [index, scenario] of scenarios.entries()) {
+    validateScenarioCandidate(scenario, index);
+  }
+  return scenarios;
+}
+var SCENARIO_KINDS_WITHOUT_REQUIRED_FIELDS = /* @__PURE__ */ new Set([
+  "initialize",
+  "tools.list",
+  "resources.list",
+  "resources.templates.list",
+  "prompts.list",
+  "tasks.list",
+  "auth.assert"
+]);
+function validateScenarioCandidate(scenario, index) {
+  if (!scenario || typeof scenario !== "object" || Array.isArray(scenario)) {
+    throw new TypeError(`Invalid scenario at index ${index}`);
+  }
+  const candidate = scenario;
+  validateScenarioIdentity(candidate, index);
+  const kind = scenarioKind(candidate, index);
+  validateScenarioOperation(candidate, kind, index);
+  validateScenarioLimits(candidate, index);
+  if (kind === "events.expect") validateEventScenario(candidate, index);
+  validateScenarioMetadata(candidate, index);
+  if (kind === "auth.assert") validateAuthScenario(candidate, index);
+}
+function validateScenarioIdentity(candidate, index) {
+  if (candidate.formatVersion !== void 0 && candidate.formatVersion !== 1) {
+    throw new TypeError(`Invalid scenario at index ${index}: unsupported formatVersion`);
+  }
+  if (typeof candidate.name !== "string" || !candidate.name.trim()) {
+    throw new TypeError(`Invalid scenario at index ${index}: name is required`);
+  }
+}
+function scenarioKind(candidate, index) {
+  const kind = candidate.kind ?? "tools.call";
+  if (typeof kind !== "string") {
+    throw new TypeError(`Invalid scenario at index ${index}: kind must be a string`);
+  }
+  return kind;
+}
+function validateScenarioOperation(candidate, kind, index) {
+  const requiredField = requiredScenarioField(kind);
+  if (requiredField && typeof candidate[requiredField] !== "string") {
+    throw new TypeError(`Invalid scenario at index ${index}: ${kind} requires ${requiredField}`);
+  }
+  if (!requiredField && !SCENARIO_KINDS_WITHOUT_REQUIRED_FIELDS.has(kind)) {
+    throw new TypeError(`Invalid scenario at index ${index}: unsupported kind ${kind}`);
+  }
+}
+function validateScenarioLimits(candidate, index) {
+  if (candidate.timeoutMs !== void 0 && (!Number.isInteger(candidate.timeoutMs) || Number(candidate.timeoutMs) < 1 || Number(candidate.timeoutMs) > 3e5)) {
+    throw new TypeError(`Invalid scenario at index ${index}: timeoutMs must be 1..300000`);
+  }
+  if (candidate.variables !== void 0 && (!Array.isArray(candidate.variables) || candidate.variables.some((entry) => typeof entry !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(entry)))) {
+    throw new TypeError(`Invalid scenario at index ${index}: variables must be environment names`);
+  }
+}
+function validateScenarioMetadata(candidate, index) {
+  if (candidate.status !== void 0 && candidate.status !== "complete" && candidate.status !== "incomplete") {
+    throw new TypeError(`Invalid scenario at index ${index}: status must be complete or incomplete`);
+  }
+  if (candidate.status === "incomplete" && typeof candidate.incompleteReason !== "string") {
+    throw new TypeError(`Invalid scenario at index ${index}: incompleteReason is required`);
+  }
+  if (candidate.sideEffect !== void 0 && (typeof candidate.sideEffect !== "string" || !["none", "idempotent", "non-idempotent"].includes(candidate.sideEffect))) {
+    throw new TypeError(`Invalid scenario at index ${index}: sideEffect is unsupported`);
+  }
+}
+function validateEventScenario(candidate, index) {
+  if (candidate.minimum !== void 0 && (!Number.isSafeInteger(candidate.minimum) || Number(candidate.minimum) < 1)) {
+    throw new TypeError(
+      `Invalid scenario at index ${index}: events.expect minimum must be a positive integer`
+    );
+  }
+}
+function validateAuthScenario(candidate, index) {
+  const expectation = candidate.expect;
+  if (typeof candidate.phase !== "string" || !expectation || typeof expectation.outcome !== "string" || !["allowed", "denied"].includes(expectation.outcome)) {
+    throw new TypeError(`Invalid scenario at index ${index}: auth.assert expectation is required`);
+  }
+}
+function createMcpFnScenarioArtifact(scenarios, options) {
+  const artifactOptions = options ?? { status: "complete" };
+  return {
+    formatVersion: 1,
+    kind: "mcpfn.scenarios",
+    ...artifactOptions,
+    scenarios: validateMcpFnScenarios(scenarios)
+  };
+}
+function isScenarioArtifact(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value;
+  if (candidate.kind !== "mcpfn.scenarios") return false;
+  if (candidate.formatVersion !== 1) {
+    throw new Error("Unsupported McpFn scenario artifact formatVersion");
+  }
+  if (candidate.status !== "complete" && candidate.status !== "incomplete") {
+    throw new Error("McpFn scenario artifact status must be complete or incomplete");
+  }
+  if (candidate.status === "incomplete" && typeof candidate.incompleteReason !== "string") {
+    throw new Error("Incomplete McpFn scenario artifact requires incompleteReason");
+  }
+  return true;
+}
+async function runScenarios(client, scenarios, options = {}) {
+  if (options.defaultTimeoutMs !== void 0 && (!Number.isInteger(options.defaultTimeoutMs) || options.defaultTimeoutMs < 1 || options.defaultTimeoutMs > 3e5)) {
+    throw new Error("defaultTimeoutMs must be an integer from 1 through 300000");
+  }
+  if (options.maxScenarios !== void 0 && (!Number.isInteger(options.maxScenarios) || options.maxScenarios < 1)) {
+    throw new Error("maxScenarios must be a positive integer");
+  }
+  if (options.maxErrorBytes !== void 0 && (!Number.isInteger(options.maxErrorBytes) || options.maxErrorBytes < 64)) {
+    throw new Error("maxErrorBytes must be an integer of at least 64");
+  }
+  if (options.maxObservedEvents !== void 0 && (!Number.isInteger(options.maxObservedEvents) || options.maxObservedEvents < 1)) {
+    throw new Error("maxObservedEvents must be a positive integer");
+  }
+  if (scenarios.length > (options.maxScenarios ?? 1e3)) {
+    throw new Error(`Scenario count exceeds the configured cap of ${options.maxScenarios ?? 1e3}`);
+  }
   const results = [];
-  for (const scenario of scenarios) {
-    const startedAt = performance.now();
-    try {
-      const result = await client.callTool(scenario.tool, scenario.arguments);
-      if (result.isError && scenario.expect?.isError === void 0) {
-        throw new McpFnAssertionError(
-          "Tool returned isError=true without an explicit expect.isError=true assertion"
-        );
+  const observedEvents = [];
+  const maxObservedEvents = options.maxObservedEvents ?? 500;
+  let droppedObservedEvents = 0;
+  let attributedDroppedObservedEvents = 0;
+  const pushResult = (result) => {
+    const newlyDropped = droppedObservedEvents - attributedDroppedObservedEvents;
+    results.push({
+      ...result,
+      ...newlyDropped > 0 ? { droppedObservedEvents: (result.droppedObservedEvents ?? 0) + newlyDropped } : {}
+    });
+    attributedDroppedObservedEvents = droppedObservedEvents;
+  };
+  const unsubscribe = client.session.onEvent((event) => {
+    observedEvents.push(event);
+    if (observedEvents.length > maxObservedEvents) {
+      observedEvents.shift();
+      droppedObservedEvents += 1;
+    }
+  });
+  let timedOutScenario;
+  try {
+    for (const scenario of scenarios) {
+      const startedAt = performance.now();
+      const operation = scenario.kind ?? "tools.call";
+      const common = {
+        formatVersion: 1,
+        name: scenario.name,
+        operation,
+        ...isToolScenario(scenario) ? { tool: scenario.tool } : {},
+        sideEffect: scenario.sideEffect ?? defaultSideEffect(operation)
+      };
+      if (timedOutScenario) {
+        pushResult({
+          ...common,
+          status: "incomplete",
+          durationMs: 0,
+          error: truncateError(`Skipped after timed-out scenario: ${timedOutScenario}`, options)
+        });
+        continue;
       }
-      if (scenario.expect?.isError !== void 0 && Boolean(result.isError) !== scenario.expect.isError) {
-        throw new McpFnAssertionError(
-          `Expected isError=${scenario.expect.isError}, received ${Boolean(result.isError)}`
-        );
+      const resolved = resolveScenarioVariables(scenario, options.variables);
+      if (resolved.missing.length > 0) {
+        pushResult({
+          ...common,
+          status: "incomplete",
+          durationMs: 0,
+          error: truncateError(
+            `Missing scenario variables: ${resolved.missing.join(", ")}`,
+            options
+          )
+        });
+        continue;
       }
-      if (scenario.expect && Object.prototype.hasOwnProperty.call(scenario.expect, "structuredContent") && stableJson(result.structuredContent) !== stableJson(scenario.expect.structuredContent)) {
-        throw new McpFnAssertionError(
-          `Structured result mismatch
+      if (scenario.status === "incomplete") {
+        pushResult({
+          ...common,
+          status: "incomplete",
+          durationMs: 0,
+          error: truncateError(scenario.incompleteReason ?? "Scenario is incomplete", options)
+        });
+        continue;
+      }
+      const timeoutMs = scenario.timeoutMs ?? options.defaultTimeoutMs ?? 3e4;
+      const controller = new AbortController();
+      let timer;
+      let timedOut = false;
+      try {
+        await Promise.race([
+          executeScenario(client, resolved.scenario, {
+            signal: controller.signal,
+            timeout: timeoutMs
+          }, observedEvents, options),
+          new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+              timedOut = true;
+              controller.abort();
+              reject(new McpFnAssertionError(`Scenario timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+          })
+        ]);
+        pushResult({
+          ...common,
+          status: "passed",
+          durationMs: performance.now() - startedAt
+        });
+      } catch (error) {
+        pushResult({
+          ...common,
+          status: "failed",
+          durationMs: performance.now() - startedAt,
+          error: truncateError(error instanceof Error ? error.message : String(error), options)
+        });
+        if (timedOut) timedOutScenario = scenario.name;
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }
+  } finally {
+    const unattributed = droppedObservedEvents - attributedDroppedObservedEvents;
+    const lastResult = results.at(-1);
+    if (lastResult && unattributed > 0) {
+      lastResult.droppedObservedEvents = (lastResult.droppedObservedEvents ?? 0) + unattributed;
+    }
+    unsubscribe();
+  }
+  return results;
+}
+function resolveScenarioVariables(scenario, supplied) {
+  const values = { ...process.env, ...supplied };
+  const required = new Set(scenario.variables ?? []);
+  const marker = /\$\{([A-Z][A-Z0-9_]*)\}/g;
+  const encodedMarker = /%24%7[Bb]([A-Z][A-Z0-9_]*)%7[Dd]/g;
+  const visit = (value) => {
+    if (typeof value === "string") {
+      for (const match of value.matchAll(marker)) required.add(match[1]);
+      for (const match of value.matchAll(encodedMarker)) required.add(match[1]);
+      return value.replace(marker, (original, name) => values[name] ?? original).replace(
+        encodedMarker,
+        (original, name) => values[name] === void 0 ? original : encodeURIComponent(values[name])
+      );
+    }
+    if (Array.isArray(value)) return value.map(visit);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [key, visit(entry)])
+      );
+    }
+    return value;
+  };
+  const resolved = visit(scenario);
+  return {
+    scenario: resolved,
+    missing: [...required].filter((name) => values[name] === void 0).sort(compareCodeUnits)
+  };
+}
+function createMcpFnScenarioReport(results, options = {}) {
+  const failed = results.filter((result) => result.status === "failed").length;
+  const incomplete = results.filter((result) => result.status === "incomplete").length;
+  const droppedObservedEvents = results.reduce(
+    (total, result) => total + (result.droppedObservedEvents ?? 0),
+    0
+  );
+  const report = {
+    formatVersion: 1,
+    kind: "mcpfn.scenario-report",
+    status: incomplete === 0 && droppedObservedEvents === 0 ? "complete" : "incomplete",
+    ...options.manifestHash ? { manifestHash: options.manifestHash } : {},
+    total: results.length,
+    passed: results.length - failed - incomplete,
+    failed,
+    incomplete,
+    droppedResults: 0,
+    droppedObservedEvents,
+    ...droppedObservedEvents > 0 ? { incompleteReason: "Observed client events exceeded maxObservedEvents" } : {},
+    results: structuredClone(results)
+  };
+  const maxBytes = options.maxBytes ?? 1048576;
+  if (!Number.isInteger(maxBytes) || maxBytes < 1024) {
+    throw new Error("maxBytes must be an integer of at least 1024");
+  }
+  if (serializedBytes(report) > maxBytes) {
+    report.status = "incomplete";
+    report.incompleteReason = "Report content exceeded maxBytes and was truncated";
+  }
+  while (serializedBytes(report) > maxBytes && report.results.length > 0) {
+    report.results.pop();
+    report.droppedResults += 1;
+  }
+  if (report.droppedResults > 0) {
+    report.status = "incomplete";
+  }
+  if (serializedBytes(report) > maxBytes) {
+    throw new Error("The minimum scenario report exceeds maxBytes");
+  }
+  return report;
+}
+function serializedBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+async function executeScenario(client, scenario, requestOptions, observedEvents, runOptions) {
+  const kind = scenario.kind ?? "tools.call";
+  if (isInventoryScenario(scenario)) {
+    await executeInventoryScenario(client, scenario, requestOptions);
+    return;
+  }
+  switch (scenario.kind) {
+    case void 0:
+    case "tools.call":
+      return executeToolScenario(client, scenario, requestOptions);
+    case "initialize":
+      return executeInitializeScenario(client, scenario);
+    case "resources.read":
+      return assertExpectedAsync(client.readResource(scenario.uri, requestOptions), scenario.expect);
+    case "resources.subscribe":
+      return client.subscribeResource(scenario.uri, requestOptions);
+    case "resources.unsubscribe":
+      return client.unsubscribeResource(scenario.uri, requestOptions);
+    case "prompts.get":
+      return assertExpectedAsync(
+        client.getPrompt(scenario.prompt, scenario.arguments, requestOptions),
+        scenario.expect
+      );
+    case "tools.call:task":
+      return assertExpectedAsync(
+        client.createToolTask(scenario.tool, scenario.arguments, scenario.task, requestOptions),
+        scenario.expect
+      );
+    case "tasks.get":
+      return assertExpectedAsync(client.getTask(scenario.taskId, requestOptions), scenario.expect);
+    case "tasks.result":
+      return assertExpectedAsync(client.getTaskResult(scenario.taskId, requestOptions), scenario.expect);
+    case "tasks.cancel":
+      return assertExpectedAsync(client.cancelTask(scenario.taskId, requestOptions), scenario.expect);
+    case "tasks.list":
+      return assertExpectedAsync(client.listTasks(scenario.cursor, requestOptions), scenario.expect);
+    case "events.expect":
+      return executeEventScenario(scenario, observedEvents);
+    case "auth.assert":
+      return executeAuthScenario(scenario, requestOptions.signal, runOptions);
+  }
+  throw new McpFnAssertionError(`Unsupported scenario operation ${kind}`);
+}
+async function executeToolScenario(client, scenario, requestOptions) {
+  const result = await client.callTool(
+    scenario.tool,
+    scenario.arguments,
+    requestOptions
+  );
+  assertToolResult(result, scenario);
+  await scenario.verify?.(result);
+}
+function assertToolResult(result, scenario) {
+  if (result.isError && scenario.expect?.isError === void 0) {
+    throw new McpFnAssertionError(
+      "Tool returned isError=true without an explicit expect.isError=true assertion"
+    );
+  }
+  if (scenario.expect?.isError !== void 0 && Boolean(result.isError) !== scenario.expect.isError) {
+    throw new McpFnAssertionError(
+      `Expected isError=${scenario.expect.isError}, received ${Boolean(result.isError)}`
+    );
+  }
+  if (scenario.expect && Object.hasOwn(scenario.expect, "structuredContent") && stableJson(result.structuredContent) !== stableJson(scenario.expect.structuredContent)) {
+    throw new McpFnAssertionError(
+      `Structured result mismatch
 expected: ${stableJson(scenario.expect.structuredContent)}
 actual:   ${stableJson(result.structuredContent)}`
-        );
+    );
+  }
+  if (scenario.expect?.structuredTextParity) assertStructuredTextParity(result);
+}
+function executeInitializeScenario(client, scenario) {
+  const actual = client.client.getServerCapabilities() ?? {};
+  if (scenario.expectCapabilities && stableJson(actual) !== stableJson(scenario.expectCapabilities)) {
+    throw new McpFnAssertionError(
+      `Capability mismatch
+expected: ${stableJson(scenario.expectCapabilities)}
+actual:   ${stableJson(actual)}`
+    );
+  }
+}
+async function executeInventoryScenario(client, scenario, requestOptions) {
+  const values = await listScenarioInventory(client, scenario.kind, requestOptions);
+  if (!scenario.expectNames) return;
+  const actual = values.map((value) => value.name).sort(compareCodeUnits);
+  const expected = [...scenario.expectNames].sort(compareCodeUnits);
+  if (stableJson(actual) !== stableJson(expected)) {
+    throw new McpFnAssertionError(
+      `Inventory mismatch
+expected: ${stableJson(expected)}
+actual:   ${stableJson(actual)}`
+    );
+  }
+}
+async function assertExpectedAsync(actual, expected) {
+  assertExpected(await actual, expected);
+}
+function executeEventScenario(scenario, observedEvents) {
+  const matching = observedEvents.filter((event) => event.kind === scenario.event);
+  if (matching.length < (scenario.minimum ?? 1)) {
+    throw new McpFnAssertionError(
+      `Expected at least ${scenario.minimum ?? 1} ${scenario.event} event(s), received ${matching.length}`
+    );
+  }
+  if (scenario.expectPayload !== void 0) {
+    assertExpected(matching.at(-1)?.payload, scenario.expectPayload);
+  }
+}
+async function executeAuthScenario(scenario, signal, runOptions) {
+  if (!runOptions.auth) {
+    throw new McpFnAssertionError("auth.assert requires a scenario auth adapter");
+  }
+  assertExpected(await runOptions.auth(scenario, signal), scenario.expect);
+}
+function truncateError(value, options) {
+  const redacted = String(redactOAuthValue(value));
+  const maxBytes = options.maxErrorBytes ?? 4096;
+  const bytes = new TextEncoder().encode(redacted);
+  if (bytes.byteLength <= maxBytes) return redacted;
+  return `${new TextDecoder().decode(bytes.slice(0, Math.max(0, maxBytes - 16)))}...[TRUNCATED]`;
+}
+function defaultSideEffect(operation) {
+  if (operation === "tools.call" || operation === "tools.call:task") {
+    return "non-idempotent";
+  }
+  if (operation === "tasks.cancel") return "idempotent";
+  return "none";
+}
+function compareCodeUnits(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+function assertExpected(actual, expected) {
+  if (expected !== void 0 && stableJson(actual) !== stableJson(expected)) {
+    throw new McpFnAssertionError(
+      `Scenario result mismatch
+expected: ${stableJson(expected)}
+actual:   ${stableJson(actual)}`
+    );
+  }
+}
+function isToolScenario(scenario) {
+  return "tool" in scenario;
+}
+function isInventoryScenario(scenario) {
+  return ["tools.list", "resources.list", "resources.templates.list", "prompts.list"].includes(scenario.kind ?? "");
+}
+function requiredScenarioField(kind) {
+  switch (kind) {
+    case "tools.call":
+    case "tools.call:task":
+      return "tool";
+    case "resources.read":
+    case "resources.subscribe":
+    case "resources.unsubscribe":
+      return "uri";
+    case "prompts.get":
+      return "prompt";
+    case "tasks.get":
+    case "tasks.result":
+    case "tasks.cancel":
+      return "taskId";
+    case "events.expect":
+      return "event";
+    default:
+      return void 0;
+  }
+}
+async function listScenarioInventory(client, kind, requestOptions) {
+  switch (kind) {
+    case "tools.list":
+      return client.listTools(requestOptions);
+    case "resources.list":
+      return client.listResources(requestOptions);
+    case "resources.templates.list":
+      return client.listResourceTemplates(requestOptions);
+    case "prompts.list":
+      return client.listPrompts(requestOptions);
+  }
+}
+
+// src/suite.ts
+import { redactOAuthValue as redactOAuthValue2 } from "@superfunctions/oauth-core";
+async function runMcpFnTargetSuite(options) {
+  const timeline = [];
+  let droppedTimelineEvents = 0;
+  const maxTimelineEvents = options.maxTimelineEvents ?? 500;
+  if (!Number.isInteger(maxTimelineEvents) || maxTimelineEvents < 1) {
+    throw new Error("maxTimelineEvents must be a positive integer");
+  }
+  const maxReportBytes = options.maxReportBytes ?? 1048576;
+  validateReportCap(maxReportBytes);
+  const consumerDiagnostic = options.client?.diagnostics;
+  const client = await McpFnTestClient.connectTarget(
+    options.target,
+    options.clientInfo ?? { name: "mcpfn-suite", version: "0.0.1" },
+    {
+      ...options.client,
+      diagnostics: async (event) => {
+        timeline.push(redactOAuthValue2(event));
+        if (timeline.length > maxTimelineEvents) {
+          timeline.shift();
+          droppedTimelineEvents += 1;
+        }
+        await consumerDiagnostic?.(event);
       }
-      if (scenario.expect?.structuredTextParity) {
-        assertStructuredTextParity(result);
+    }
+  );
+  const execution = await (async () => {
+    try {
+      if (options.manifest) {
+        await assertManifestContract(client, options.manifest, {
+          expectedToolNames: options.expectedToolNames
+        });
       }
-      await scenario.verify?.(result);
-      results.push({
-        name: scenario.name,
-        tool: scenario.tool,
-        status: "passed",
-        durationMs: performance.now() - startedAt
-      });
-    } catch (error) {
-      results.push({
-        name: scenario.name,
-        tool: scenario.tool,
-        status: "failed",
-        durationMs: performance.now() - startedAt,
-        error: error instanceof Error ? error.message : String(error)
-      });
+      const results2 = await runScenarios(client, options.scenarios ?? [], options.scenarioRun);
+      return {
+        results: results2,
+        server: client.session.getServerVersion(),
+        capabilities: client.session.getServerCapabilities()
+      };
+    } finally {
+      await client.close();
     }
+  })();
+  const results = execution.results;
+  const failed = results.filter((result) => result.status === "failed").length;
+  const incomplete = results.filter((result) => result.status === "incomplete").length;
+  const droppedObservedEvents = results.reduce(
+    (total, result) => total + (result.droppedObservedEvents ?? 0),
+    0
+  );
+  const artifactIncomplete = incomplete > 0 || droppedTimelineEvents > 0 || droppedObservedEvents > 0;
+  const report = {
+    formatVersion: 1,
+    kind: "mcpfn.target-suite-report",
+    status: artifactIncomplete ? "incomplete" : "complete",
+    runtime: { node: process.version, scenarioFormatVersion: 1 },
+    ok: failed === 0 && !artifactIncomplete,
+    target: redactOAuthValue2(
+      options.target.describe()
+    ),
+    server: execution.server,
+    capabilities: execution.capabilities,
+    manifestChecked: Boolean(options.manifest),
+    ...options.manifest ? { manifestHash: options.manifest.hash } : {},
+    total: results.length,
+    passed: results.length - failed - incomplete,
+    failed,
+    incomplete,
+    droppedResults: 0,
+    droppedObservedEvents,
+    ...droppedTimelineEvents > 0 || droppedObservedEvents > 0 ? {
+      incompleteReason: [
+        ...droppedTimelineEvents > 0 ? ["Diagnostic timeline exceeded maxTimelineEvents"] : [],
+        ...droppedObservedEvents > 0 ? ["Observed client events exceeded maxObservedEvents"] : []
+      ].join("; ")
+    } : {},
+    timeline,
+    droppedTimelineEvents,
+    results
+  };
+  return enforceReportCap(report, maxReportBytes);
+}
+function enforceReportCap(report, maxBytes) {
+  validateReportCap(maxBytes);
+  const bounded = structuredClone(report);
+  if (jsonBytes(bounded) > maxBytes) {
+    bounded.ok = false;
+    bounded.status = "incomplete";
+    bounded.incompleteReason = "Report content exceeded maxReportBytes and was truncated";
+  }
+  while (jsonBytes(bounded) > maxBytes && bounded.results.length > 0) {
+    bounded.results.pop();
+    bounded.droppedResults += 1;
+  }
+  if (jsonBytes(bounded) > maxBytes) {
+    bounded.target = { kind: report.target.kind };
+    bounded.server = void 0;
+    bounded.capabilities = void 0;
+    bounded.timeline = [];
+    bounded.droppedTimelineEvents += report.timeline.length;
+  }
+  if (bounded.droppedResults > 0 || jsonBytes(bounded) > maxBytes) {
+    bounded.ok = false;
+    bounded.status = "incomplete";
+    bounded.incompleteReason = "Report content exceeded maxReportBytes and was truncated";
+  }
+  if (jsonBytes(bounded) > maxBytes) {
+    throw new Error("The minimum target suite report exceeds maxReportBytes");
+  }
+  return bounded;
+}
+function validateReportCap(maxBytes) {
+  if (!Number.isInteger(maxBytes) || maxBytes < 1024) {
+    throw new Error("maxReportBytes must be an integer of at least 1024");
   }
-  return results;
+}
+function jsonBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
 }
 export {
   MCPFN_HOST_PROFILES,
+  MCPFN_NAMED_OAUTH_HOST_FIXTURES,
   MCPFN_OAUTH_EXTENSION_GRANTS,
   McpFnAssertionError,
   McpFnAuthAssertionError,
@@ -1157,15 +1953,22 @@ export {
   bearerCredential,
   buildOfficialConformanceArgs,
   checkHostCompatibility,
+  createAuthenticatedConformanceProxy,
   createFetchAuthTarget,
+  createMcpFnScenario,
+  createMcpFnScenarioArtifact,
+  createMcpFnScenarioReport,
   createOAuthClientMetadataFixture,
   createOAuthClientMetadataVariants,
   createPkcePair,
   parseBearerChallenge,
   runAuthRegressionSuite,
+  runAuthenticatedOfficialConformance,
+  runMcpFnTargetSuite,
   runOfficialConformance,
   runScenarios,
   stableJson,
-  startMockOAuthAuthorizationServer
+  startMockOAuthAuthorizationServer,
+  validateMcpFnScenarios
 };
 //# sourceMappingURL=index.js.map