@mcpfn/testing 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -1,9 +1,11 @@
 import { ClientCapabilities, Implementation, Tool, CallToolResult, CreateTaskResult, Task, ListTasksResult, Resource, ResourceTemplate, ReadResourceResult, Prompt, GetPromptResult, CompleteRequest, CompleteResult, ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
-import { McpFnServer, McpFnManifest } from '@mcpfn/core';
-import { McpFnClient, McpFnClientMediatedHandlers, McpFnClientEventSink, McpFnDiagnosticSink, McpFnTarget, McpFnClientEventKind, McpFnTargetDescriptor, McpFnDiagnosticEvent } from '@mcpfn/client';
+import { McpFnServer, McpFnManifest, McpFnSchemaIssue } from '@mcpfn/core';
+import { McpFnClientMediatedHandlers, McpFnClientEventSink, McpFnDiagnosticSink, McpFnClient, McpFnTarget, McpFnStreamableHttpTargetOptions, McpFnClientEventKind, McpFnTargetDescriptor, McpFnDiagnosticEvent, McpFnDiagnosticPhase } from '@mcpfn/client';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 export { MCPFN_NAMED_OAUTH_HOST_FIXTURES, MCPFN_OAUTH_EXTENSION_GRANTS, McpFnAuthAssertionError, McpFnAuthCredential, McpFnAuthCredentialKind, McpFnAuthCredentialRequest, McpFnAuthProbeScenario, McpFnAuthProviderAdapter, McpFnAuthProviderCapabilities, McpFnAuthRegressionOptions, McpFnAuthScenarioResult, McpFnAuthTarget, McpFnBearerChallenge, McpFnFetchAuthTargetOptions, McpFnMockOAuthAuthorizationServer, McpFnMockOAuthServerOptions, McpFnMockOAuthTokenSet, McpFnNamedOAuthHostFixture, McpFnOAuthCallback, McpFnOAuthClientMetadata, McpFnOAuthClientMetadataFixtureOptions, McpFnOAuthClientMetadataVariants, McpFnPkcePair, McpFnStartMockOAuthServerOptions, McpFnStartedMockOAuthServer, apiKeyCredential, assertAuthRegressionSuite, assertAuthorizationCodeClientMetadata, assertBearerResourceChallenge, bearerCredential, createFetchAuthTarget, createOAuthClientMetadataFixture, createOAuthClientMetadataVariants, createPkcePair, parseBearerChallenge, runAuthRegressionSuite, startMockOAuthAuthorizationServer } from './auth.cjs';
+import { OAuthClientMetadata } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { McpFnClientRegistrationSource } from '@mcpfn/auth';
 import '@modelcontextprotocol/sdk/server/auth/types.js';
 
 interface McpFnTestClientOptions {
@@ -14,6 +16,11 @@ interface McpFnTestClientOptions {
     configure?(client: Client): void | Promise<void>;
     diagnostics?: McpFnDiagnosticSink;
 }
+/** Test-client cleanup failed and remains owned by this retryable error. */
+declare class McpFnTestClientCleanupError extends Error {
+    constructor(close: () => Promise<void>, cause: unknown);
+    retryCleanup(): Promise<void>;
+}
 declare class McpFnTestClient<TContext = undefined> {
     readonly session: McpFnClient;
     private constructor();
@@ -22,6 +29,8 @@ declare class McpFnTestClient<TContext = undefined> {
         name: string;
         version: string;
     }, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
+    /** Create the session owner before connecting, so failed initialization remains closeable. */
+    static createTarget<TContext = undefined>(target: McpFnTarget, info?: Implementation, options?: McpFnTestClientOptions): McpFnTestClient<TContext>;
     static connectTarget<TContext = undefined>(target: McpFnTarget, info?: Implementation, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
     listTools(options?: RequestOptions): Promise<Tool[]>;
     callTool(name: string, args?: Record<string, unknown>, options?: RequestOptions): Promise<CallToolResult>;
@@ -57,104 +66,196 @@ declare function assertStructuredTextParity(result: {
     structuredContent?: Record<string, unknown>;
 }): void;
 
-declare const OFFICIAL_CONFORMANCE_VERSION = "0.1.16";
-interface OfficialConformanceOptions {
-    url: string;
-    suite?: "active" | "all" | "pending";
-    scenario?: string;
-    expectedFailures?: string;
-    outputDir?: string;
-    specVersion?: string;
-    verbose?: boolean;
-    cwd?: string;
-    stdio?: "inherit" | "pipe";
-}
-interface OfficialConformanceResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
+type McpFnFixtureSideEffect = "read-only" | "idempotent" | "non-idempotent";
+interface McpFnClientProfileFixtureExpectation {
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+    errorCode?: string;
+    lifecycleStage?: string;
+    validationIssue?: Partial<Pick<McpFnSchemaIssue, "instancePath" | "schemaPath" | "keyword" | "rejectedProperty" | "missingProperty">>;
 }
-interface AuthenticatedConformanceProxy {
-    /** Loopback URL to pass to the official conformance runner. */
-    url: string;
-    close(): Promise<void>;
+interface McpFnClientProfileFixture {
+    name: string;
+    tool: string;
+    /** Values are executed but never copied into compatibility reports. */
+    arguments?: Record<string, unknown>;
+    sideEffect: McpFnFixtureSideEffect;
+    source?: "minimal-valid" | "captured-failure";
+    expect?: McpFnClientProfileFixtureExpectation;
 }
-interface AuthenticatedConformanceProxyOptions {
-    /** Fixed loopback MCP URL. Requests cannot select a different origin or path. */
-    url: string;
-    /** Headers injected into requests using the proxy's own authority. Values are never logged. */
-    headers: HeadersInit;
+interface McpFnSchemaPortabilityPolicy {
+    /** Treat otherwise-valid compatibility-reducing keywords as failures. */
+    warningsAsErrors?: boolean;
+    /** Suppress warnings for explicitly reviewed keywords. */
+    allowKeywords?: readonly string[];
 }
-interface AuthenticatedOfficialConformanceOptions extends OfficialConformanceOptions {
-    headers: HeadersInit;
+interface McpFnSchemaPortabilityIssue {
+    severity: "error" | "warning";
+    code: "schema-invalid" | "schema-dialect-unsupported" | "schema-portability-warning";
+    path: string;
+    keyword?: string;
+    message: string;
 }
-/**
- * Start a loopback-only streaming proxy for runners that cannot send auth
- * headers. Authenticated requests use one fixed upstream authority and path.
- * Host-manipulation probes are forwarded without injected credentials.
- */
-declare function createAuthenticatedConformanceProxy(options: AuthenticatedConformanceProxyOptions): Promise<AuthenticatedConformanceProxy>;
-declare function buildOfficialConformanceArgs(options: OfficialConformanceOptions): string[];
-declare function runOfficialConformance(options: OfficialConformanceOptions): Promise<OfficialConformanceResult>;
-/** Run the pinned official suite against an authenticated MCP endpoint. */
-declare function runAuthenticatedOfficialConformance(options: AuthenticatedOfficialConformanceOptions): Promise<OfficialConformanceResult>;
-
-type McpFnServerFeature = "tools" | "resources" | "prompts" | "completions" | "tasks" | "logging";
-interface McpFnHostProfile {
-    id: string;
+interface McpFnClientProfileSnapshotTool {
     name: string;
-    protocolVersions: string[];
-    serverFeatures: McpFnServerFeature[];
-    clientFeatures?: {
-        sampling?: boolean;
-        elicitation?: Array<"form" | "url">;
-        roots?: boolean;
+    hash: string;
+}
+interface McpFnClientProfileSnapshot {
+    formatVersion: 1;
+    kind: "mcpfn.client-profile-snapshot";
+    profile: {
+        id: string;
+        version: string;
     };
-    extensions?: string[];
+    catalogHash: string;
+    tools: McpFnClientProfileSnapshotTool[];
 }
-interface McpFnHostCompatibilityIssue {
-    severity: "incompatible" | "degraded";
-    code: string;
-    path: string;
-    message: string;
+interface McpFnClientProfileSnapshotChange {
+    kind: "added" | "removed" | "modified";
+    tool: string;
+    beforeHash?: string;
+    afterHash?: string;
 }
-interface McpFnHostCompatibilityResult {
-    status: "compatible" | "degraded" | "incompatible";
+interface McpFnClientProfileSnapshotDiff {
     compatible: boolean;
-    issues: McpFnHostCompatibilityIssue[];
-}
-declare const MCPFN_HOST_PROFILES: {
-    readonly toolsOnly: {
-        readonly id: "mcpfn/tools-only";
-        readonly name: "Tools-only MCP host";
-        readonly protocolVersions: ["2025-03-26", "2025-06-18", "2025-11-25"];
-        readonly serverFeatures: ["tools"];
+    changes: McpFnClientProfileSnapshotChange[];
+    summary: {
+        added: number;
+        removed: number;
+        modified: number;
     };
-    readonly fullProtocol: {
-        readonly id: "mcpfn/full-protocol";
-        readonly name: "Full protocol MCP host";
-        readonly protocolVersions: ["2025-03-26", "2025-06-18", "2025-11-25"];
-        readonly serverFeatures: ["tools", "resources", "prompts", "completions", "tasks", "logging"];
-        readonly clientFeatures: {
-            readonly sampling: true;
-            readonly elicitation: ["form", "url"];
-            readonly roots: true;
-        };
+}
+interface McpFnClientProfileContractCase {
+    id: string;
+    version: string;
+    target: McpFnTarget;
+    clientInfo?: Implementation;
+    capabilities?: ClientCapabilities;
+    client?: Omit<McpFnTestClientOptions, "capabilities">;
+    fixtures?: readonly McpFnClientProfileFixture[];
+    expectedSnapshot?: McpFnClientProfileSnapshot;
+    portability?: McpFnSchemaPortabilityPolicy;
+}
+interface RunMcpFnClientProfileContractsOptions {
+    profiles: readonly McpFnClientProfileContractCase[];
+    /** Explicit opt-in for fixtures that could mutate state. Defaults to false. */
+    allowSideEffects?: boolean;
+    /** Aggregate JSON size cap. Defaults to 1 MiB. */
+    maxReportBytes?: number;
+}
+interface McpFnClientProfileFixtureResult {
+    name: string;
+    tool: string;
+    source: "minimal-valid" | "captured-failure";
+    status: "passed" | "failed" | "incomplete";
+    code?: string;
+    error?: string;
+}
+interface McpFnClientProfileContractResult {
+    profile: {
+        id: string;
+        version: string;
     };
-    readonly mcpApps: {
-        readonly id: "mcpfn/mcp-apps";
-        readonly name: "Full protocol host with MCP Apps";
-        readonly protocolVersions: ["2025-11-25"];
-        readonly serverFeatures: ["tools", "resources", "prompts", "completions", "tasks", "logging"];
-        readonly clientFeatures: {
-            readonly sampling: true;
-            readonly elicitation: ["form", "url"];
-            readonly roots: true;
-        };
-        readonly extensions: ["io.modelcontextprotocol/ui"];
+    status: "complete" | "incomplete";
+    ok: boolean;
+    phase?: "connect" | "catalog" | "fixtures" | "close";
+    snapshot?: McpFnClientProfileSnapshot;
+    snapshotMatches?: boolean;
+    portability: McpFnSchemaPortabilityIssue[];
+    fixtures: McpFnClientProfileFixtureResult[];
+    error?: string;
+}
+interface McpFnClientProfileContractReport {
+    formatVersion: 1;
+    kind: "mcpfn.client-profile-contract-report";
+    status: "complete" | "incomplete";
+    ok: boolean;
+    profiles: McpFnClientProfileContractResult[];
+    droppedProfiles: number;
+    incompleteReason?: string;
+}
+/** A complete bounded report with retry ownership for unfinished target cleanup. */
+declare class McpFnClientProfileContractCleanupError extends Error {
+    readonly report: McpFnClientProfileContractReport;
+    private readonly owners;
+    constructor(report: McpFnClientProfileContractReport, owners: readonly McpFnTestClientCleanupError[]);
+    retryCleanup(): Promise<void>;
+}
+declare function createMcpFnClientProfileSnapshot(profile: {
+    id: string;
+    version: string;
+}, tools: readonly Tool[]): McpFnClientProfileSnapshot;
+declare function validateMcpFnClientProfileSnapshot(value: unknown): McpFnClientProfileSnapshot;
+declare function diffMcpFnClientProfileSnapshots(beforeValue: unknown, afterValue: unknown): McpFnClientProfileSnapshotDiff;
+declare function validateMcpFnSchemaPortability(schema: unknown, path: string, policy?: McpFnSchemaPortabilityPolicy): McpFnSchemaPortabilityIssue[];
+/** Exercise every profile through the production target/client list-and-call lifecycle. */
+declare function runMcpFnClientProfileContracts(options: RunMcpFnClientProfileContractsOptions): Promise<McpFnClientProfileContractReport>;
+
+/** Retain released credentials only for the lifetime of a report operation. */
+declare function beginTargetCredentialRedaction(target: McpFnTarget): () => void;
+declare class McpFnRedactionLimitError extends Error {
+    constructor(message?: string);
+}
+/** No typed artifact can preserve this authored structure without exposing a credential. */
+declare class McpFnStructuralCredentialCollisionError extends McpFnRedactionLimitError {
+    constructor();
+}
+/** Remove known opaque credential values as well as credential-shaped fields. */
+declare function redactTargetCredentials<T>(target: McpFnTarget, value: T, options?: {
+    preserveKeys?: boolean;
+    redactionMarker?: string;
+}): T;
+/** Assert completed bounded output without applying payload traversal limits. */
+declare function assertTargetArtifactSafe(target: McpFnTarget, value: string): void;
+/** Redact authenticated conformance output using the acquired credential. */
+declare function redactRemoteCredential<T>(credential: McpFnRemoteCredential, value: T, options?: {
+    preserveKeys?: boolean;
+}): T;
+type McpFnRemoteCredentialKind = "api-key" | "oauth" | "custom";
+interface McpFnRemoteCredential {
+    /** Credential headers are applied only to the fixed target origin. */
+    headers: HeadersInit;
+    kind?: McpFnRemoteCredentialKind;
+    label?: string;
+}
+interface McpFnRemoteCredentialContext {
+    url: string;
+    requestId: string;
+    signal?: AbortSignal;
+}
+/**
+ * Application-owned credential lifecycle for external MCP targets. McpFn
+ * acquires once per target open, revokes before disposal, and never serializes
+ * the returned headers into descriptors or reports. If acquisition rejects, the
+ * provider must roll back its own partial resources; no lease has been returned.
+ */
+interface McpFnRemoteCredentialProvider {
+    acquire(context: McpFnRemoteCredentialContext): McpFnRemoteCredential | Promise<McpFnRemoteCredential>;
+    revoke?(credential: McpFnRemoteCredential, context: McpFnRemoteCredentialContext): void | Promise<void>;
+    dispose?(credential: McpFnRemoteCredential, context: McpFnRemoteCredentialContext): void | Promise<void>;
+}
+interface McpFnRemoteCredentialLease {
+    credential: McpFnRemoteCredential;
+    release(): Promise<void>;
+    /** The lifecycle stage that most recently prevented credential release. */
+    cleanupPhase(): "token-revocation" | "transport-close";
+}
+interface McpFnAuthenticatedHttpTargetOptions extends Omit<McpFnStreamableHttpTargetOptions, "authProvider" | "requestInit"> {
+    credential: McpFnRemoteCredential | McpFnRemoteCredentialProvider;
+    requestInit?: Omit<RequestInit, "headers" | "redirect"> & {
+        headers?: HeadersInit;
     };
-};
-declare function checkHostCompatibility(manifest: McpFnManifest, profile: McpFnHostProfile): McpFnHostCompatibilityResult;
+}
+/** Create a provider for an already-bounded API key or OAuth-derived token. */
+declare function staticRemoteCredentialProvider(credential: McpFnRemoteCredential): McpFnRemoteCredentialProvider;
+/** Acquire a credential and return an idempotent revoke-then-dispose lease. */
+declare function acquireRemoteCredential(source: McpFnRemoteCredential | McpFnRemoteCredentialProvider, context: McpFnRemoteCredentialContext): Promise<McpFnRemoteCredentialLease>;
+/**
+ * A URL-plus-credential target for non-McpFn servers. It delegates MCP and
+ * transport behavior to the production @mcpfn/client session engine.
+ */
+declare function authenticatedHttpTarget(url: string | URL, options: McpFnAuthenticatedHttpTargetOptions): McpFnTarget;
+declare function validateRemoteCredentialHeaders(value: HeadersInit): Headers;
 
 type McpFnScenarioSideEffect = "none" | "idempotent" | "non-idempotent";
 interface McpFnScenarioBase {
@@ -286,6 +387,8 @@ interface McpFnScenarioResult {
     error?: string;
     /** Observed client events discarded while this scenario was running. */
     droppedObservedEvents?: number;
+    /** Dropped observed events whose original payload could not be safely redacted. */
+    redactionOmittedObservedEvents?: number;
 }
 interface McpFnScenarioReport {
     formatVersion: 1;
@@ -298,6 +401,7 @@ interface McpFnScenarioReport {
     incomplete: number;
     droppedResults: number;
     droppedObservedEvents: number;
+    redactionOmittedObservedEvents?: number;
     incompleteReason?: string;
     results: McpFnScenarioResult[];
 }
@@ -340,10 +444,16 @@ interface RunMcpFnTargetSuiteOptions {
 interface McpFnTargetSuiteReport {
     formatVersion: 1;
     kind: "mcpfn.target-suite-report";
+    /** Generated reports require retained target proof for derived encodings. */
+    artifactValidation?: "target-aware";
     status: "complete" | "incomplete";
     runtime: {
         node: string;
         scenarioFormatVersion: 1;
+        reportSchemaVersion: string;
+        packages: {
+            testing: string;
+        };
     };
     ok: boolean;
     target: McpFnTargetDescriptor;
@@ -357,12 +467,239 @@ interface McpFnTargetSuiteReport {
     incomplete: number;
     droppedResults: number;
     droppedObservedEvents: number;
+    redactionOmittedObservedEvents?: number;
     incompleteReason?: string;
+    failure?: McpFnReportFailure;
     timeline: McpFnDiagnosticEvent[];
     droppedTimelineEvents: number;
     results: McpFnScenarioResult[];
 }
+/** Final cleanup failed. The bounded report is a snapshot; retain this error to retry. */
+declare class McpFnTargetSuiteCleanupError extends Error {
+    readonly report: McpFnTargetSuiteReport;
+    constructor(report: McpFnTargetSuiteReport, close: () => Promise<void>);
+    retryCleanup(): Promise<void>;
+}
+/** Report serialization failed after cleanup ownership had already transferred. */
+declare class McpFnTargetSuiteArtifactCleanupError extends Error {
+    constructor(close: () => Promise<void>, cause: Error);
+    retryCleanup(): Promise<void>;
+}
 /** Runs local, stdio, HTTP, or custom targets through the production session engine. */
 declare function runMcpFnTargetSuite(options: RunMcpFnTargetSuiteOptions): Promise<McpFnTargetSuiteReport>;
 
-export { type AssertManifestContractOptions, type AuthenticatedConformanceProxy, type AuthenticatedConformanceProxyOptions, type AuthenticatedOfficialConformanceOptions, MCPFN_HOST_PROFILES, McpFnAssertionError, type McpFnAuthScenario, type McpFnCreateTaskScenario, type McpFnEventScenario, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnInitializeScenario, type McpFnInventoryScenario, type McpFnPromptScenario, type McpFnRecordedOperation, type McpFnRecordedOperationResult, type McpFnResourceScenario, type McpFnScenario, type McpFnScenarioArtifact, type McpFnScenarioBase, type McpFnScenarioReport, type McpFnScenarioResult, type McpFnScenarioRunOptions, type McpFnScenarioSideEffect, type McpFnServerFeature, type McpFnTargetSuiteReport, type McpFnTaskScenario, McpFnTestClient, type McpFnTestClientOptions, type McpFnToolScenario, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, type RunMcpFnTargetSuiteOptions, assertManifestContract, assertStructuredTextParity, buildOfficialConformanceArgs, checkHostCompatibility, createAuthenticatedConformanceProxy, createMcpFnScenario, createMcpFnScenarioArtifact, createMcpFnScenarioReport, runAuthenticatedOfficialConformance, runMcpFnTargetSuite, runOfficialConformance, runScenarios, stableJson, validateMcpFnScenarios };
+declare const MCPFN_TESTING_VERSION: string;
+declare const MCPFN_REPORT_SCHEMA_VERSION = "1.0.0";
+type McpFnFailureLayer = "mcpfn-preflight" | "authorization-server" | "resource-server" | "mcp-initialization" | "scenario" | "upstream-conformance";
+interface McpFnReportFailure {
+    name: string;
+    message: string;
+    layer: McpFnFailureLayer;
+    code?: string;
+    phase?: string;
+    details?: Record<string, unknown>;
+}
+interface McpFnJunitOptions {
+    /** Aggregate XML size cap after serialization. Defaults to 1 MiB. */
+    maxBytes?: number;
+}
+interface McpFnTargetSuiteJsonOptions {
+    /** JSON indentation. Defaults to compact output; maximum 10 spaces. */
+    space?: number;
+    /** Include a final newline in the validated artifact. */
+    trailingNewline?: boolean;
+}
+/** Serialize the exact JSON representation while target proof is retained. */
+declare function serializeMcpFnTargetSuiteReport(report: McpFnTargetSuiteReport, options?: McpFnTargetSuiteJsonOptions): string;
+/** Release target-owned proof after every required report encoding is complete. */
+declare function disposeMcpFnTargetSuiteReport(report: McpFnTargetSuiteReport): void;
+declare function normalizeMcpFnReportFailure(error: unknown, fallbackPhase?: McpFnDiagnosticPhase | "scenario" | "upstream-conformance"): McpFnReportFailure;
+/** Serialize a redacted target-suite report as bounded JUnit XML. */
+declare function createMcpFnTargetSuiteJUnit(report: McpFnTargetSuiteReport, options?: McpFnJunitOptions): string;
+
+declare const OFFICIAL_CONFORMANCE_VERSION = "0.1.16";
+interface OfficialConformanceOptions {
+    url: string;
+    suite?: "active" | "all" | "pending";
+    scenario?: string;
+    expectedFailures?: string;
+    outputDir?: string;
+    specVersion?: string;
+    verbose?: boolean;
+    cwd?: string;
+    stdio?: "inherit" | "pipe";
+    /** Environment names removed before spawning the upstream runner. */
+    sensitiveEnvironmentVariables?: readonly string[];
+}
+interface OfficialConformanceResult {
+    formatVersion: 1;
+    kind: "mcpfn.official-conformance-report";
+    ok: boolean;
+    suiteVersion: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    failure?: McpFnReportFailure;
+    /** Credential cleanup failure, separate from the upstream runner diagnosis. */
+    cleanupFailure?: McpFnReportFailure;
+}
+interface AuthenticatedConformanceProxy {
+    /** Loopback URL to pass to the official conformance runner. */
+    url: string;
+    close(): Promise<void>;
+}
+interface AuthenticatedConformanceProxyOptions {
+    /** Fixed loopback MCP URL. Requests cannot select a different origin or path. */
+    url: string;
+    /** Headers injected into requests using the proxy's own authority. Values are never logged. */
+    headers: HeadersInit;
+}
+interface AuthenticatedOfficialConformanceOptions extends OfficialConformanceOptions {
+    /** Preferred typed credential lifecycle. */
+    credential?: McpFnRemoteCredential | McpFnRemoteCredentialProvider;
+    /** Backward-compatible static header input. Prefer credential. */
+    headers?: HeadersInit;
+}
+/**
+ * Start a loopback-only streaming proxy for runners that cannot send auth
+ * headers. Authenticated requests use one fixed upstream authority and path.
+ * Host-manipulation probes are forwarded without injected credentials.
+ */
+declare function createAuthenticatedConformanceProxy(options: AuthenticatedConformanceProxyOptions): Promise<AuthenticatedConformanceProxy>;
+declare function buildOfficialConformanceArgs(options: OfficialConformanceOptions): string[];
+declare function buildOfficialConformanceEnvironment(sensitiveNames?: readonly string[], source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+declare function runOfficialConformance(options: OfficialConformanceOptions): Promise<OfficialConformanceResult>;
+/** Cleanup failed after retries. Retain this error and call retryCleanup(). */
+declare class McpFnConformanceCleanupError extends Error {
+    readonly result?: OfficialConformanceResult | undefined;
+    constructor(release: () => Promise<void>, result?: OfficialConformanceResult | undefined);
+    retryCleanup(): Promise<void>;
+}
+/**
+ * Run the pinned official suite against an authenticated MCP endpoint.
+ * Always captures stdio (even when inherit is requested) to redact credentials.
+ * outputDir is rejected before acquisition; only the returned redacted result is safe to persist.
+ */
+declare function runAuthenticatedOfficialConformance(options: AuthenticatedOfficialConformanceOptions): Promise<OfficialConformanceResult>;
+
+type McpFnServerFeature = "tools" | "resources" | "prompts" | "completions" | "tasks" | "logging";
+interface McpFnHostProfile {
+    id: string;
+    name: string;
+    protocolVersions: string[];
+    serverFeatures: McpFnServerFeature[];
+    clientFeatures?: {
+        sampling?: boolean;
+        elicitation?: Array<"form" | "url">;
+        roots?: boolean;
+    };
+    extensions?: string[];
+}
+interface McpFnHostCompatibilityIssue {
+    severity: "incompatible" | "degraded";
+    code: string;
+    path: string;
+    message: string;
+}
+interface McpFnHostCompatibilityResult {
+    status: "compatible" | "degraded" | "incompatible";
+    compatible: boolean;
+    issues: McpFnHostCompatibilityIssue[];
+}
+declare const MCPFN_HOST_PROFILES: {
+    readonly toolsOnly: {
+        readonly id: "mcpfn/tools-only";
+        readonly name: "Tools-only MCP host";
+        readonly protocolVersions: ["2025-03-26", "2025-06-18", "2025-11-25"];
+        readonly serverFeatures: ["tools"];
+    };
+    readonly fullProtocol: {
+        readonly id: "mcpfn/full-protocol";
+        readonly name: "Full protocol MCP host";
+        readonly protocolVersions: ["2025-03-26", "2025-06-18", "2025-11-25"];
+        readonly serverFeatures: ["tools", "resources", "prompts", "completions", "tasks", "logging"];
+        readonly clientFeatures: {
+            readonly sampling: true;
+            readonly elicitation: ["form", "url"];
+            readonly roots: true;
+        };
+    };
+    readonly mcpApps: {
+        readonly id: "mcpfn/mcp-apps";
+        readonly name: "Full protocol host with MCP Apps";
+        readonly protocolVersions: ["2025-11-25"];
+        readonly serverFeatures: ["tools", "resources", "prompts", "completions", "tasks", "logging"];
+        readonly clientFeatures: {
+            readonly sampling: true;
+            readonly elicitation: ["form", "url"];
+            readonly roots: true;
+        };
+        readonly extensions: ["io.modelcontextprotocol/ui"];
+    };
+};
+declare function checkHostCompatibility(manifest: McpFnManifest, profile: McpFnHostProfile): McpFnHostCompatibilityResult;
+
+interface McpFnHostedRegistrationFixture {
+    clientId: string;
+    source: McpFnClientRegistrationSource;
+    metadata: OAuthClientMetadata;
+}
+interface McpFnHostedAuthorizationRequestFixture {
+    clientId: string;
+    redirectUri: string;
+    resource: string;
+    scopes: string[];
+    state: string;
+    codeVerifier: string;
+}
+interface McpFnHostedTokenRequestFixture {
+    grantType: string;
+    /** Optional independently-authored code override for negative token-exchange cases. */
+    code?: string;
+    refreshToken?: string;
+    refreshAfterExchange?: boolean;
+}
+interface McpFnHostedAuthorizationCase {
+    id: string;
+    host: "chatgpt" | "claude" | "generic";
+    registration: McpFnHostedRegistrationFixture;
+    authorization: McpFnHostedAuthorizationRequestFixture;
+    token?: McpFnHostedTokenRequestFixture;
+    expected: {
+        outcome: "allowed" | "rejected";
+        errorCode?: string;
+        phase?: "client-registration" | "authorization-request" | "token-exchange" | "token-refresh";
+    };
+}
+interface McpFnHostedAuthorizationTargetAdapter {
+    issuer: string;
+    prepareRegistration(fixture: McpFnHostedRegistrationFixture): Promise<void>;
+    request(request: Request): Promise<Response>;
+}
+interface McpFnHostedAuthorizationCaseResult {
+    formatVersion: 1;
+    id: string;
+    host: McpFnHostedAuthorizationCase["host"];
+    status: "passed" | "failed";
+    phase: "client-registration" | "authorization-request" | "token-exchange" | "token-refresh";
+    layer: "mcpfn-preflight" | "authorization-server";
+    responseStatus?: number;
+    errorCode?: string;
+    error?: string;
+}
+interface McpFnHostedAuthorizationFixtureOptions {
+    issuer: string;
+    resource: string;
+    chatgptRedirectUri?: string;
+    claudeRedirectUri?: string;
+}
+/**
+ * Provider-shaped role-3 fixtures. Registration metadata and authorization
+ * requests are separate objects so redirect, grant, and deployment drift can
+ * fail instead of being generated from one self-consistent source.
+ */
+declare function createHostedAuthorizationFixtures(options: McpFnHostedAuthorizationFixtureOptions): McpFnHostedAuthorizationCase[];
+/** Run the independently-configured hosted-authorization matrix. */
+declare function runHostedAuthorizationRegression(target: McpFnHostedAuthorizationTargetAdapter, fixtures: readonly McpFnHostedAuthorizationCase[]): Promise<McpFnHostedAuthorizationCaseResult[]>;
+
+export { type AssertManifestContractOptions, type AuthenticatedConformanceProxy, type AuthenticatedConformanceProxyOptions, type AuthenticatedOfficialConformanceOptions, MCPFN_HOST_PROFILES, MCPFN_REPORT_SCHEMA_VERSION, MCPFN_TESTING_VERSION, McpFnAssertionError, type McpFnAuthScenario, type McpFnAuthenticatedHttpTargetOptions, type McpFnClientProfileContractCase, McpFnClientProfileContractCleanupError, type McpFnClientProfileContractReport, type McpFnClientProfileContractResult, type McpFnClientProfileFixture, type McpFnClientProfileFixtureExpectation, type McpFnClientProfileFixtureResult, type McpFnClientProfileSnapshot, type McpFnClientProfileSnapshotChange, type McpFnClientProfileSnapshotDiff, type McpFnClientProfileSnapshotTool, McpFnConformanceCleanupError, type McpFnCreateTaskScenario, type McpFnEventScenario, type McpFnFailureLayer, type McpFnFixtureSideEffect, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnHostedAuthorizationCase, type McpFnHostedAuthorizationCaseResult, type McpFnHostedAuthorizationFixtureOptions, type McpFnHostedAuthorizationRequestFixture, type McpFnHostedAuthorizationTargetAdapter, type McpFnHostedRegistrationFixture, type McpFnHostedTokenRequestFixture, type McpFnInitializeScenario, type McpFnInventoryScenario, type McpFnJunitOptions, type McpFnPromptScenario, type McpFnRecordedOperation, type McpFnRecordedOperationResult, McpFnRedactionLimitError, type McpFnRemoteCredential, type McpFnRemoteCredentialContext, type McpFnRemoteCredentialKind, type McpFnRemoteCredentialLease, type McpFnRemoteCredentialProvider, type McpFnReportFailure, type McpFnResourceScenario, type McpFnScenario, type McpFnScenarioArtifact, type McpFnScenarioBase, type McpFnScenarioReport, type McpFnScenarioResult, type McpFnScenarioRunOptions, type McpFnScenarioSideEffect, type McpFnSchemaPortabilityIssue, type McpFnSchemaPortabilityPolicy, type McpFnServerFeature, McpFnStructuralCredentialCollisionError, McpFnTargetSuiteArtifactCleanupError, McpFnTargetSuiteCleanupError, type McpFnTargetSuiteJsonOptions, type McpFnTargetSuiteReport, type McpFnTaskScenario, McpFnTestClient, McpFnTestClientCleanupError, type McpFnTestClientOptions, type McpFnToolScenario, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, type RunMcpFnClientProfileContractsOptions, type RunMcpFnTargetSuiteOptions, acquireRemoteCredential, assertManifestContract, assertStructuredTextParity, assertTargetArtifactSafe, authenticatedHttpTarget, beginTargetCredentialRedaction, buildOfficialConformanceArgs, buildOfficialConformanceEnvironment, checkHostCompatibility, createAuthenticatedConformanceProxy, createHostedAuthorizationFixtures, createMcpFnClientProfileSnapshot, createMcpFnScenario, createMcpFnScenarioArtifact, createMcpFnScenarioReport, createMcpFnTargetSuiteJUnit, diffMcpFnClientProfileSnapshots, disposeMcpFnTargetSuiteReport, normalizeMcpFnReportFailure, redactRemoteCredential, redactTargetCredentials, runAuthenticatedOfficialConformance, runHostedAuthorizationRegression, runMcpFnClientProfileContracts, runMcpFnTargetSuite, runOfficialConformance, runScenarios, serializeMcpFnTargetSuiteReport, stableJson, staticRemoteCredentialProvider, validateMcpFnClientProfileSnapshot, validateMcpFnScenarios, validateMcpFnSchemaPortability, validateRemoteCredentialHeaders };