refactor(mcp): make analysis states unrepresentable (#468)

* refactor(config): parse capability settings into exact states

* refactor(runtime): encode replay and process outcomes exactly

* refactor: make analysis states unrepresentable

* refactor(mcp): register canonical schemas with SDK

* fix: preserve capability and catalog invariants

* fix(build): remove stale compiled modules

* fix(replay): update real verifier policy dependency

* fix(package): verify the complete MCP catalog

* fix(test): supply complete replay reload policy

* refactor(contracts): centralize output schema lookup

* refactor(mcp): delegate protocol boundaries to SDK

* fix(browser): approve real source capture

* fix(mcp): preserve catalog guidance
This commit is contained in:
morluto
2026-08-10 02:28:11 +08:00
committed by GitHub
parent 6901edc05d
commit b8a9da0c0f
271 changed files with 5970 additions and 5699 deletions
+184 -151
View File
@@ -5,50 +5,65 @@ import {
createRequestStateCodec,
McpServer,
PROTOCOL_VERSION_META_KEY,
type ServerContext,
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { silentLogger, type Logger } from "../logger.js";
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerEvidenceResources } from "./registerEvidenceResources.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import type {
JavaScriptReplayHost,
JavaScriptReplayPolicy,
JavaScriptReplayRunner,
} from "../application/JavaScriptReplayPlanning.js";
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
import { MANAGED_RUNTIME_DISABLED } from "../application/ManagedRuntimeCorrelationService.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { silentLogger, type Logger } from "../logger.js";
import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
import { mcpClientMetadata, mcpEnvelopeValue } from "./mcpClientMetadata.js";
import {
PROCESS_CAPTURE_ELICITATION_POLICY,
type ProcessCaptureElicitationState,
} from "./ProcessCaptureElicitation.js";
import { registerApplicationTools } from "./registerApplicationTools.js";
import { registerArtifactTools } from "./registerArtifactTools.js";
import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
import { registerBrowserTools } from "./registerBrowserTools.js";
import { registerElectronTools } from "./registerElectronTools.js";
import { registerEnhancedTools } from "./registerEnhancedTools.js";
import { registerEvidenceResources } from "./registerEvidenceResources.js";
import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
import { registerManagedTools } from "./registerManagedTools.js";
import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
import { registerNativeTools } from "./registerNativeTools.js";
import { registerOfficialTools } from "./registerOfficialTools.js";
import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerSessionTools } from "./registerSessionTools.js";
import type { SessionAvailability } from "./sessionAvailabilityPolicy.js";
import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
import {
DENY_EVIDENCE_FILE_POLICY,
DENY_PROCESS_POLICY,
} from "./sessionToolPolicies.js";
import { installDynamicToolAvailability } from "./DynamicToolAvailability.js";
const TARGET_FREE_INSTRUCTIONS =
"ASAR/JavaScript -> analyze_javascript_application; archive/package -> open_binary(path), then inspect_artifact/inventory_artifact (active target); managed PE/CLI -> inspect_managed_artifact; browser/Electron -> list_browser_targets/list_electron_targets; approved -> capture_browser_scenario/capture_electron_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Start with binary_session; use tools/list; capabilities via binary_session. Use summaries, cite Evidence IDs; Never repeat identical analysis or read full Evidence.";
const ACTIVE_TARGET_INSTRUCTIONS =
"REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
import type {
JavaScriptReplayHost,
JavaScriptReplayPolicy,
JavaScriptReplayRunner,
} from "../application/JavaScriptReplayPlanning.js";
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
import {
PROCESS_CAPTURE_ELICITATION_POLICY,
type ProcessCaptureElicitationState,
} from "./ProcessCaptureElicitation.js";
import { LazyToolCatalog } from "./LazyToolCatalog.js";
export interface CreateServerOptions {
readonly logger?: Logger;
readonly processPolicy?: ProcessExecutionPolicy;
readonly processPolicy?: () => ProcessExecutionPolicy;
readonly evidenceFilePolicy?: EvidenceFilePolicy;
readonly investigationInputRoots?: readonly string[];
readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy;
@@ -59,18 +74,11 @@ export interface CreateServerOptions {
readonly electronActiveObservation?: ElectronActiveObservationPort;
readonly javascriptRuntimeObservation?: JavaScriptRuntimeObservationPort;
readonly artifactIntegrityContinueEnabled?: () => boolean;
readonly javascriptReplayPolicy?: JavaScriptReplayPolicy;
readonly javascriptReplayPolicy?: () => JavaScriptReplayPolicy;
readonly javascriptReplayHost?: JavaScriptReplayHost;
readonly javascriptReplayRunner?: JavaScriptReplayRunner;
readonly managedRuntimePolicy?: ManagedRuntimePolicy;
readonly managedRuntimePolicy?: () => ManagedRuntimePolicy;
readonly availabilityPolicy?: () => SessionAvailability;
readonly loadOptionalProviders?: () => Promise<{
readonly browserObservation: BrowserObservationPort;
readonly browserScenarioCapture: BrowserScenarioCapturePort;
readonly electronObservation: ElectronObservationPort;
readonly electronActiveObservation: ElectronActiveObservationPort;
readonly javascriptRuntimeObservation: JavaScriptRuntimeObservationPort;
}>;
}
const installSessionToolAvailability = (
@@ -80,7 +88,7 @@ const installSessionToolAvailability = (
) => {
if (session === undefined) return undefined;
const policy = sessionAvailabilityPolicy(options.availabilityPolicy, {
processPolicy: options.processPolicy ?? DENY_PROCESS_POLICY,
processPolicy: options.processPolicy?.() ?? DENY_PROCESS_POLICY,
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
investigationInputRoots: options.investigationInputRoots ?? [],
optionalFeatures: {
@@ -92,13 +100,14 @@ const installSessionToolAvailability = (
options.permissionAuthority !== undefined,
v8InspectorObservationEnabled:
options.javascriptRuntimeObservation !== undefined,
javascriptReplayEnabled: options.javascriptReplayPolicy?.enabled ?? false,
managedRuntimeEnabled: options.managedRuntimePolicy?.enabled ?? false,
javascriptReplayEnabled:
options.javascriptReplayPolicy?.().status === "enabled",
managedRuntimeEnabled:
options.managedRuntimePolicy?.().status === "enabled",
},
});
return {
policy,
controller: installDynamicToolAvailability(server, session, policy),
};
};
@@ -107,9 +116,7 @@ type ProcessCaptureElicitation = {
typeof createRequestStateCodec<ProcessCaptureElicitationState>
>;
readonly supported: (context: {
readonly mcpReq: {
readonly envelope?: Readonly<Record<string, unknown>>;
};
readonly mcpReq: Pick<ServerContext["mcpReq"], "envelope">;
}) => boolean;
readonly now: typeof Date.now;
readonly consumedNonces: Map<string, number>;
@@ -121,8 +128,11 @@ const createProcessCaptureElicitation = (
stateCodec,
supported: (context) => {
const envelope = context.mcpReq.envelope;
const version = envelope?.[PROTOCOL_VERSION_META_KEY];
const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
const version = mcpEnvelopeValue(envelope, PROTOCOL_VERSION_META_KEY);
const capabilities = mcpEnvelopeValue(
envelope,
CLIENT_CAPABILITIES_META_KEY,
);
return (
typeof version === "string" &&
PROCESS_CAPTURE_ELICITATION_POLICY.protocolVersions.some(
@@ -137,93 +147,6 @@ const createProcessCaptureElicitation = (
consumedNonces: new Map<string, number>(),
});
const createOptionalProviderLoader = (options: CreateServerOptions) => {
let optionalProviders:
| ReturnType<NonNullable<CreateServerOptions["loadOptionalProviders"]>>
| undefined;
return () => {
optionalProviders ??= options
.loadOptionalProviders?.()
.catch((cause: unknown) => {
optionalProviders = undefined;
throw cause;
});
return optionalProviders;
};
};
const createLazyToolCatalog = ({
server,
analysis,
session,
options,
toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy,
startedAt,
processCaptureElicitation,
}: {
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly toolLogger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
readonly activeTarget: ReturnType<
typeof createSessionRecorders
>["activeTarget"];
readonly recordEvidence: ReturnType<
typeof createSessionRecorders
>["recordEvidence"];
readonly recordEvidenceWithUnknown: ReturnType<
typeof createSessionRecorders
>["recordEvidenceWithUnknown"];
readonly availabilityPolicy: CreateServerOptions["availabilityPolicy"];
readonly startedAt: string;
readonly processCaptureElicitation: ProcessCaptureElicitation;
}): LazyToolCatalog => {
const loadOptionalProviders = createOptionalProviderLoader(options);
return new LazyToolCatalog(
server,
async (kind) => {
const needsObservationProviders =
kind === "browser-provider" ||
kind === "electron-provider" ||
kind === "runtime-provider";
const [{ hydrateServerToolFamily }, loadedOptionalProviders] =
await Promise.all([
import("./hydrateServerTools.js"),
needsObservationProviders ? loadOptionalProviders() : undefined,
]);
const hydratedOptions =
loadedOptionalProviders === undefined
? options
: { ...options, ...loadedOptionalProviders };
await hydrateServerToolFamily({
kind,
server,
analysis,
session,
options: hydratedOptions,
context: {
logger: toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy,
startedAt,
processCaptureElicitation,
},
});
},
session !== undefined,
);
};
const createMcpServer = (
processCaptureStateCodec: ProcessCaptureElicitation["stateCodec"],
session: BinarySessionPort | undefined,
@@ -235,8 +158,7 @@ const createMcpServer = (
},
{
capabilities: {
tools: { listChanged: true },
resources: { listChanged: true, subscribe: true },
resources: { subscribe: true },
},
inputRequired: {
maxRounds: 3,
@@ -270,13 +192,10 @@ export const createServer = (
ttlSeconds: PROCESS_CAPTURE_ELICITATION_POLICY.stateTtlSeconds,
});
const server = createMcpServer(processCaptureStateCodec, session);
const dynamicTools = installSessionToolAvailability(server, session, options);
const availability = installSessionToolAvailability(server, session, options);
server.server.onclose = () => {
permissionAuthority?.clearSessionGrants();
};
if (dynamicTools !== undefined)
server.server.oninitialized = () => server.sendToolListChanged();
session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
registerServerIdentityResource(server, startedAt);
const toolLogger = logger.child({ layer: "server" });
const { activeTarget, recordEvidence, recordEvidenceWithUnknown } =
@@ -284,34 +203,38 @@ export const createServer = (
const processCaptureElicitation = createProcessCaptureElicitation(
processCaptureStateCodec,
);
const lazyTools = createLazyToolCatalog({
const toolContext: ServerToolContext = {
server,
analysis,
session,
options,
toolLogger,
logger: toolLogger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
availabilityPolicy: dynamicTools?.policy,
startedAt,
processCaptureElicitation,
});
lazyTools.register();
};
registerBinaryAnalysisTools(toolContext);
registerObservationTools(toolContext);
registerGuidedPrompts(server, analysis, session);
if (session !== undefined) {
registerEvidenceResources(server, session);
registerSessionTools(server, session, toolLogger, {
...options,
...(availability === undefined
? {}
: { availabilityPolicy: availability.policy }),
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
startedAt,
processCaptureElicitation,
});
}
dynamicTools?.controller.synchronize();
const close = server.close.bind(server);
server.close = async () => {
await lazyTools.close();
await close();
};
return server;
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
const createSessionRecorders = (
server: McpServer,
session: BinarySessionPort | undefined,
@@ -337,6 +260,120 @@ const createSessionRecorders = (
},
});
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
readonly server: McpServer;
readonly analysis: AnalysisOperationPort;
readonly session: BinarySessionPort | undefined;
readonly options: CreateServerOptions;
readonly logger: Logger;
readonly permissionAuthority: PermissionAuthority | undefined;
}
const registerBinaryAnalysisTools = ({
server,
analysis,
session,
options,
logger,
permissionAuthority,
activeTarget,
recordEvidence,
recordEvidenceWithUnknown,
}: ServerToolContext): void => {
const recordUnknown =
session === undefined
? undefined
: (input: Parameters<typeof session.recordUnknown>[0]) =>
session.recordUnknown(input);
const analysisOptions = {
logger,
activeTarget,
recordEvidence,
recordUnknown,
};
registerOfficialTools(server, analysis, analysisOptions);
registerEnhancedTools(server, analysis, {
...analysisOptions,
analysisProfile:
session === undefined ? undefined : () => session.analysisProfile(),
});
const evidenceOptions = { logger, activeTarget, recordEvidence };
registerNativeTools(server, analysis, evidenceOptions);
registerArtifactTools(server, analysis, {
...evidenceOptions,
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
});
registerManagedTools(server, analysis, {
...evidenceOptions,
session,
});
if (session !== undefined)
registerManagedWorkflowTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
session,
runtime: {
policy:
options.managedRuntimePolicy ?? (() => MANAGED_RUNTIME_DISABLED),
authority: permissionAuthority,
},
});
};
const registerObservationTools = ({
server,
session,
options,
logger,
permissionAuthority,
recordEvidence,
recordEvidenceWithUnknown,
}: ServerToolContext): void => {
const common = { logger, permissionAuthority, recordEvidence };
registerBrowserTools(server, {
...common,
browser: options.browserObservation,
});
registerBrowserScenarioTool(server, {
...common,
provider: options.browserScenarioCapture,
});
registerElectronTools(server, {
...common,
electron: options.electronObservation,
electronActive: options.electronActiveObservation,
});
registerJavaScriptRuntimeObservationTools(server, {
...common,
runtime: options.javascriptRuntimeObservation,
});
registerApplicationTools(server, {
logger,
recordEvidence,
recordEvidenceWithUnknown,
evidenceLookup:
session === undefined
? undefined
: (evidenceId) => session.evidenceById(evidenceId),
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
permissionAuthority,
retainCoverageWorkspace:
session === undefined
? undefined
: (workspace) =>
session.retainReconstructionCoverageWorkspace(workspace),
replay: {
policy:
options.javascriptReplayPolicy ?? (() => ({ status: "disabled" })),
host: options.javascriptReplayHost ?? new SystemJavaScriptReplayHost(),
runner:
options.javascriptReplayRunner ?? new LinuxJavaScriptReplayRunner(),
authority: permissionAuthority,
},
});
};
const registerServerIdentityResource = (
server: McpServer,
startedAt: string,
@@ -349,10 +386,9 @@ const registerServerIdentityResource = (
description: "Live package, SDK, protocol, and catalog identity.",
mimeType: "application/json",
},
async (uri) => {
async (uri, context) => {
const { createServerIdentity } = await import("../serverIdentity.js");
const client = server.server.getClientVersion();
const protocolVersion = server.server.getNegotiatedProtocolVersion();
const { client, protocolVersion } = mcpClientMetadata(context);
return {
contents: [
{
@@ -373,6 +409,3 @@ const registerServerIdentityResource = (
},
);
};
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);