refactor: compose investigation record ownership (#845)

This commit is contained in:
N0zoM1z0
2026-10-07 12:10:45 +08:00
committed by GitHub
parent bc2cd8b874
commit ce73c3fed2
27 changed files with 627 additions and 127 deletions
+2 -1
View File
@@ -1,3 +1,4 @@
import type { EvidenceReader } from "../application/investigation/InvestigationRecordPort.js";
import { z } from "zod";
import { uniqueSorted } from "../domain/canonicalOrdering.js";
@@ -138,7 +139,7 @@ const evidenceCandidates = (
};
type LedgerEvidence = ReturnType<
BinarySessionPort["exportEvidenceBundle"]
EvidenceReader["exportEvidenceBundle"]
>["records"][number];
const evidenceValues = (
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { ToolContract } from "../contracts/toolContractTypes.js";
import type { AndroidOperation } from "../domain/androidAnalysis.js";
@@ -14,7 +14,7 @@ export const registerAndroidTools = (
server: McpServer,
service: AndroidAnalysisService,
logger: Logger,
recordEvidence?: BinarySessionPort["recordEvidence"],
recordEvidence?: EvidenceWriter["recordEvidence"],
): void => {
const handler = (contract: ToolContract<AndroidOperation>) => {
const name = contract.name;
+8 -4
View File
@@ -1,12 +1,16 @@
import type { BinarySessionPort } from "../../application/BinarySession.js";
import type {
EvidenceWriter,
EvidenceReader,
EvidenceUnknownWriter,
} from "../../application/investigation/InvestigationRecordPort.js";
import type { Logger } from "../../logger.js";
/** Shared services for registering JavaScript application graph workflows. */
export interface ApplicationToolRegistration {
readonly logger: Logger;
readonly evidenceById: BinarySessionPort["evidenceById"] | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly evidenceById: EvidenceReader["evidenceById"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| EvidenceUnknownWriter["recordEvidenceWithUnknown"]
| undefined;
}
+2 -2
View File
@@ -1,7 +1,7 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
@@ -15,7 +15,7 @@ export const registerArtifactTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
import { captureBrowserScenario } from "../application/BrowserScenarioCaptureService.js";
import { BROWSER_SCENARIO_TOOL_CONTRACTS } from "../contracts/browserScenarioToolContracts.js";
@@ -19,7 +19,7 @@ interface BrowserScenarioToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly provider: BrowserScenarioCapturePort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register the browser scenario tool with execution-time provider diagnostics. */
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import {
analyzeWebBundle,
@@ -35,7 +35,7 @@ interface BrowserToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly browser: BrowserObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
interface BrowserToolContext {
+2 -2
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
import { captureElectronScenario } from "../application/ElectronActiveObservationService.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
@@ -34,7 +34,7 @@ interface ElectronToolRegistration {
readonly activeLoadFailure?: OptionalProviderLoadFailure | undefined;
readonly electron: ElectronObservationPort | undefined;
readonly electronActive: ElectronActiveObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
interface ElectronToolContext {
+8 -5
View File
@@ -1,3 +1,7 @@
import type {
EvidenceWriter,
UnknownRegistryPort,
} from "../application/investigation/InvestigationRecordPort.js";
import type {
CallToolResult,
McpServer,
@@ -5,7 +9,6 @@ import type {
} from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
EnhancedTools,
type ValidatedEnhancedCall,
@@ -34,8 +37,8 @@ export interface EnhancedToolRegistration {
readonly analysisProfile:
| (() => AnalysisProfileCommitment | undefined)
| undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
}
/** Register composed workflows against the same port as direct bridge tools. */
@@ -319,7 +322,7 @@ interface WorkflowUnknownInput {
readonly name: string;
readonly result: JsonValue;
readonly evidenceId: string;
readonly recordUnknown: BinarySessionPort["recordUnknown"] | undefined;
readonly recordUnknown: UnknownRegistryPort["recordUnknown"] | undefined;
}
const recordWorkflowUnknowns = ({
@@ -328,7 +331,7 @@ const recordWorkflowUnknowns = ({
evidenceId,
recordUnknown,
}: WorkflowUnknownInput):
| ReturnType<BinarySessionPort["recordUnknown"]>
| ReturnType<UnknownRegistryPort["recordUnknown"]>
| { readonly ok: true; readonly value: null } => {
if (
!["trace_feature", "trace_call_path", "inspect_native_api"].includes(
+2 -2
View File
@@ -1,10 +1,10 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type {
AnalysisOperation,
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
@@ -19,7 +19,7 @@ import { createArtifactExtractionDestination } from "../application/ArtifactExtr
interface EvidenceToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly sourceEvidence?: (
operation: Exclude<AnalysisOperation, "health">,
result: import("../domain/jsonValue.js").JsonValue,
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { ToolContract } from "../contracts/toolContractTypes.js";
import type { FirmwareOperation } from "../domain/firmwareAnalysis.js";
@@ -14,7 +14,7 @@ export const registerFirmwareTools = (
server: McpServer,
service: FirmwareAnalysisService,
logger: Logger,
recordEvidence?: BinarySessionPort["recordEvidence"],
recordEvidence?: EvidenceWriter["recordEvidence"],
): void => {
const handler =
(contract: ToolContract<FirmwareOperation>) =>
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
optionalProviderUnavailable,
type OptionalProviderLoadFailure,
@@ -5,7 +6,6 @@ import {
import { err } from "../domain/result.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
import {
listJavaScriptRuntimeTargets,
@@ -26,7 +26,7 @@ interface RuntimeToolRegistration {
readonly logger: Logger;
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
readonly runtime: JavaScriptRuntimeObservationPort | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register passive Inspector tools even when policy keeps them unavailable. */
+2 -1
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
@@ -18,7 +19,7 @@ export const registerManagedTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly session: BinarySessionPort | undefined;
},
): void => {
@@ -1,12 +1,16 @@
import type {
EvidenceWriter,
EvidenceUnknownWriter,
} from "../../application/investigation/InvestigationRecordPort.js";
import type { BinarySessionPort } from "../../application/BinarySession.js";
import type { Logger } from "../../logger.js";
/** Shared services for registering managed-code workflow tools. */
export interface ManagedWorkflowToolRegistration {
readonly logger: Logger;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| EvidenceUnknownWriter["recordEvidenceWithUnknown"]
| undefined;
readonly session: BinarySessionPort;
}
+2 -2
View File
@@ -1,7 +1,7 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { NATIVE_TOOL_CONTRACTS } from "../contracts/nativeToolContracts.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
@@ -14,7 +14,7 @@ export const registerNativeTools = (
options: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
registerEvidenceTools(server, analysis, NATIVE_TOOL_CONTRACTS, options);
+3 -3
View File
@@ -1,3 +1,4 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
import { z } from "zod";
@@ -5,7 +6,6 @@ import type {
AnalysisExecution,
AnalysisOperationPort,
} from "../application/AnalysisProvider.js";
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/officialToolContracts.js";
@@ -28,7 +28,7 @@ import { toCallToolResult } from "./toolResult.js";
export interface OfficialToolRegistration {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
}
/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
@@ -53,7 +53,7 @@ const registerOfficialTool = (
registration: {
readonly logger: Logger;
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
server.registerTool(
+2 -2
View File
@@ -1,6 +1,6 @@
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { exportWebScriptsValidated } from "../application/WebScriptExportService.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { Logger } from "../logger.js";
@@ -13,7 +13,7 @@ export const registerWebScriptTool = (
server: McpServer,
options: {
readonly logger: Logger;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
},
): void => {
const contract = toolContract("export_web_scripts");
+2 -2
View File
@@ -1,11 +1,11 @@
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
import type { Evidence } from "../domain/evidence.js";
import { ok, type Result } from "../domain/result.js";
/** Record source evidence in order, stopping at the first session rejection. */
export const recordSessionEvidenceSources = (
recordEvidence: BinarySessionPort["recordEvidence"] | undefined,
recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
sources: readonly Evidence[],
): Result<null, EvidenceIntegrityError> => {
for (const source of sources) {