356 lines
11 KiB
TypeScript
356 lines
11 KiB
TypeScript
import type { McpServer } from "@modelcontextprotocol/server";
|
|
|
|
import type { BinarySessionPort } from "../application/BinarySession.js";
|
|
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
|
|
import {
|
|
readEvidenceBundle,
|
|
writeEvidenceBundle,
|
|
} from "../application/EvidenceBundleFiles.js";
|
|
import {
|
|
exportEvidenceBundleInputSchema,
|
|
importEvidenceBundleInputSchema,
|
|
listUnknownsInputSchema,
|
|
snapshotEvidenceBundleInputSchema,
|
|
SESSION_TOOL_CONTRACTS,
|
|
verifyUnknownResolutionInputSchema,
|
|
} from "../contracts/toolContracts.js";
|
|
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
|
|
import {
|
|
AnalysisProtocolError,
|
|
PermissionRequiredError,
|
|
type AnalysisError,
|
|
} from "../domain/errors.js";
|
|
import {
|
|
recordUnknownInputSchema,
|
|
updateUnknownInputSchema,
|
|
} from "../domain/residualUnknown.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import { safeParseToolInput } from "./toolInputValidation.js";
|
|
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
|
import { toCallToolResult } from "./toolResult.js";
|
|
|
|
interface EvidenceToolRegistration {
|
|
readonly server: McpServer;
|
|
readonly session: BinarySessionPort;
|
|
readonly exportContract: (typeof SESSION_TOOL_CONTRACTS)[3];
|
|
readonly importContract: (typeof SESSION_TOOL_CONTRACTS)[4];
|
|
readonly snapshotContract: (typeof SESSION_TOOL_CONTRACTS)[19];
|
|
readonly filePolicy: EvidenceFilePolicy;
|
|
readonly permissionAuthority?: PermissionAuthority;
|
|
}
|
|
|
|
/** Register evidence bundle import and export tools. */
|
|
export const registerEvidenceTools = (
|
|
registration: EvidenceToolRegistration,
|
|
): void => {
|
|
registerExportEvidenceTool(registration);
|
|
registerImportEvidenceTool(registration);
|
|
registerSnapshotEvidenceTool(registration);
|
|
};
|
|
|
|
const registerExportEvidenceTool = ({
|
|
server,
|
|
session,
|
|
exportContract,
|
|
filePolicy,
|
|
permissionAuthority,
|
|
}: EvidenceToolRegistration): void => {
|
|
server.registerTool(
|
|
exportContract.name,
|
|
toolRegistrationOptions(exportContract),
|
|
async (input) => {
|
|
const parsedInput = safeParseToolInput(
|
|
exportEvidenceBundleInputSchema,
|
|
input,
|
|
exportContract.name,
|
|
);
|
|
if (!parsedInput.ok) return toCallToolResult(parsedInput, exportContract);
|
|
const parsed = parsedInput.value;
|
|
const bundle = session.exportEvidenceBundle();
|
|
const denied = await authorizeEvidencePath({
|
|
authority: permissionAuthority,
|
|
capability: "evidence_write",
|
|
path: parsed.path,
|
|
access: "write",
|
|
operationIdentity: `export_evidence:${parsed.path}`,
|
|
});
|
|
if (denied !== undefined) return toCallToolResult(denied, exportContract);
|
|
const written = await writeEvidenceBundle(
|
|
bundle,
|
|
parsed.path,
|
|
parsed.overwrite,
|
|
filePolicy,
|
|
);
|
|
return written.ok
|
|
? toCallToolResult(
|
|
ok({
|
|
path: written.value.path,
|
|
bytes: written.value.bytes,
|
|
records: bundle.records.length,
|
|
unknowns: bundle.unknowns.length,
|
|
}),
|
|
exportContract,
|
|
)
|
|
: toCallToolResult(written, exportContract);
|
|
},
|
|
);
|
|
};
|
|
|
|
const registerSnapshotEvidenceTool = ({
|
|
server,
|
|
session,
|
|
snapshotContract,
|
|
}: EvidenceToolRegistration): void => {
|
|
server.registerTool(
|
|
snapshotContract.name,
|
|
toolRegistrationOptions(snapshotContract),
|
|
(input) => {
|
|
const parsed = safeParseToolInput(
|
|
snapshotEvidenceBundleInputSchema,
|
|
input,
|
|
snapshotContract.name,
|
|
);
|
|
if (!parsed.ok) return toCallToolResult(parsed, snapshotContract);
|
|
const snapshot = session.snapshotEvidenceBundle();
|
|
if (!snapshot.ok) return toCallToolResult(snapshot, snapshotContract);
|
|
const value = {
|
|
bundle_digest: snapshot.value.bundleDigest,
|
|
bundle_version: snapshot.value.bundleVersion,
|
|
bytes: snapshot.value.bytes,
|
|
records: snapshot.value.records,
|
|
unknowns: snapshot.value.unknowns,
|
|
bundle_uri: snapshot.value.uri,
|
|
} as const;
|
|
return toCallToolResult(ok(value), snapshotContract, {
|
|
resourceLinks: [
|
|
{
|
|
uri: snapshot.value.uri,
|
|
name: snapshot.value.bundleDigest,
|
|
description: "Immutable session-retained Evidence v2 bundle",
|
|
},
|
|
],
|
|
});
|
|
},
|
|
);
|
|
};
|
|
|
|
const registerImportEvidenceTool = ({
|
|
server,
|
|
session,
|
|
importContract,
|
|
filePolicy,
|
|
permissionAuthority,
|
|
}: EvidenceToolRegistration): void => {
|
|
server.registerTool(
|
|
importContract.name,
|
|
toolRegistrationOptions(importContract),
|
|
async (input) => {
|
|
const parsedInput = safeParseToolInput(
|
|
importEvidenceBundleInputSchema,
|
|
input,
|
|
importContract.name,
|
|
);
|
|
if (!parsedInput.ok) return toCallToolResult(parsedInput, importContract);
|
|
const path = parsedInput.value.path;
|
|
const denied = await authorizeEvidencePath({
|
|
authority: permissionAuthority,
|
|
capability: "evidence_read",
|
|
path,
|
|
access: "read",
|
|
operationIdentity: `import_evidence:${path}`,
|
|
});
|
|
if (denied !== undefined) return toCallToolResult(denied, importContract);
|
|
const loaded = await readEvidenceBundle(path, filePolicy);
|
|
if (!loaded.ok) return toCallToolResult(loaded, importContract);
|
|
const imported = session.importEvidenceBundle(loaded.value);
|
|
return imported.ok
|
|
? toCallToolResult(
|
|
ok({
|
|
imported: imported.value,
|
|
total: session.exportEvidenceBundle().records.length,
|
|
}),
|
|
importContract,
|
|
)
|
|
: toCallToolResult(imported, importContract);
|
|
},
|
|
);
|
|
};
|
|
|
|
interface EvidenceAuthorizationInput {
|
|
readonly authority: PermissionAuthority | undefined;
|
|
readonly capability: "evidence_read" | "evidence_write";
|
|
readonly path: string;
|
|
readonly access: "read" | "write";
|
|
readonly operationIdentity: string;
|
|
}
|
|
|
|
const authorizeEvidencePath = async (
|
|
input: EvidenceAuthorizationInput,
|
|
): Promise<Result<never, AnalysisError> | undefined> => {
|
|
if (input.authority === undefined) return undefined;
|
|
const authorized = await input.authority.authorize(
|
|
{
|
|
capability: input.capability,
|
|
roots: [input.path],
|
|
executables: [],
|
|
environment_names: [],
|
|
network: "none",
|
|
mount: false,
|
|
operation_identity: input.operationIdentity,
|
|
},
|
|
input.access,
|
|
);
|
|
return authorized.ok ? undefined : permissionFailure(authorized);
|
|
};
|
|
|
|
interface UnknownToolRegistration {
|
|
readonly server: McpServer;
|
|
readonly session: BinarySessionPort;
|
|
readonly contracts: typeof SESSION_TOOL_CONTRACTS;
|
|
}
|
|
|
|
/** Register residual-unknown query and mutation tools. */
|
|
export const registerUnknownTools = ({
|
|
server,
|
|
session,
|
|
contracts,
|
|
}: UnknownToolRegistration): void => {
|
|
const listContract = contracts[14];
|
|
const recordContract = contracts[15];
|
|
const updateContract = contracts[16];
|
|
const verifyContract = contracts[17];
|
|
server.registerTool(
|
|
listContract.name,
|
|
toolRegistrationOptions(listContract),
|
|
(input) => {
|
|
const parsed = safeParseToolInput(
|
|
listUnknownsInputSchema,
|
|
input,
|
|
listContract.name,
|
|
);
|
|
if (!parsed.ok) return toCallToolResult(parsed, listContract);
|
|
const filters = parsed.value;
|
|
const all = session.listUnknowns({
|
|
...(filters.status === undefined ? {} : { status: filters.status }),
|
|
...(filters.severity === undefined
|
|
? {}
|
|
: { severity: filters.severity }),
|
|
...(filters.domain === undefined ? {} : { domain: filters.domain }),
|
|
});
|
|
const items = all
|
|
.slice(filters.offset, filters.offset + filters.limit)
|
|
.map((unknown) => ({
|
|
unknown,
|
|
uri: `rea://unknown/${unknown.unknown_id}`,
|
|
}));
|
|
const nextOffset =
|
|
filters.offset + items.length < all.length
|
|
? filters.offset + items.length
|
|
: null;
|
|
return toCallToolResult(
|
|
ok({
|
|
items,
|
|
offset: filters.offset,
|
|
limit: filters.limit,
|
|
total: all.length,
|
|
next_offset: nextOffset,
|
|
has_more: nextOffset !== null,
|
|
}),
|
|
listContract,
|
|
{
|
|
resourceLinks: items.map((unknown) => ({
|
|
uri: unknown.uri,
|
|
name: unknown.unknown.unknown_id,
|
|
description: `Current ${unknown.unknown.status} residual unknown revision`,
|
|
})),
|
|
},
|
|
);
|
|
},
|
|
);
|
|
server.registerTool(
|
|
recordContract.name,
|
|
toolRegistrationOptions(recordContract),
|
|
(input) => {
|
|
const parsed = safeParseToolInput(
|
|
recordUnknownInputSchema,
|
|
input,
|
|
recordContract.name,
|
|
);
|
|
if (!parsed.ok) return toCallToolResult(parsed, recordContract);
|
|
const result = session.recordUnknown(parsed.value);
|
|
return result.ok
|
|
? toCallToolResult(result, recordContract, {
|
|
resourceLinks: [
|
|
{
|
|
uri: `rea://unknown/${result.value.unknown_id}`,
|
|
name: result.value.unknown_id,
|
|
description: "Current residual unknown head",
|
|
},
|
|
],
|
|
})
|
|
: toCallToolResult(result, recordContract);
|
|
},
|
|
);
|
|
server.registerTool(
|
|
updateContract.name,
|
|
toolRegistrationOptions(updateContract),
|
|
(input) => {
|
|
const parsed = safeParseToolInput(
|
|
updateUnknownInputSchema,
|
|
input,
|
|
updateContract.name,
|
|
);
|
|
if (!parsed.ok) return toCallToolResult(parsed, updateContract);
|
|
const result = session.updateUnknown(parsed.value);
|
|
if (result.ok)
|
|
void server.server
|
|
.sendResourceUpdated({
|
|
uri: `rea://unknown/${result.value.unknown_id}`,
|
|
})
|
|
.catch(() => undefined);
|
|
return result.ok
|
|
? toCallToolResult(result, updateContract, {
|
|
resourceLinks: [
|
|
{
|
|
uri: `rea://unknown/${result.value.unknown_id}`,
|
|
name: result.value.unknown_id,
|
|
description: "Updated residual unknown head",
|
|
},
|
|
],
|
|
})
|
|
: toCallToolResult(result, updateContract);
|
|
},
|
|
);
|
|
server.registerTool(
|
|
verifyContract.name,
|
|
toolRegistrationOptions(verifyContract),
|
|
(input) => {
|
|
const parsed = safeParseToolInput(
|
|
verifyUnknownResolutionInputSchema,
|
|
input,
|
|
verifyContract.name,
|
|
);
|
|
return parsed.ok
|
|
? toCallToolResult(
|
|
session.verifyUnknownResolution(parsed.value.unknown_id),
|
|
verifyContract,
|
|
)
|
|
: toCallToolResult(parsed, verifyContract);
|
|
},
|
|
);
|
|
};
|
|
|
|
const permissionFailure = (
|
|
failure: Awaited<ReturnType<PermissionAuthority["authorize"]>>,
|
|
): Result<never, AnalysisError> => {
|
|
if (failure.ok)
|
|
return err(new AnalysisProtocolError("Expected a denied permission"));
|
|
return err(
|
|
failure.error instanceof PermissionRequiredError
|
|
? failure.error
|
|
: new AnalysisProtocolError(failure.error.message, {
|
|
cause: failure.error,
|
|
}),
|
|
);
|
|
};
|