Files
MikrotikManager/backend/src/modules/mcp/path-verification.ts
T

177 lines
16 KiB
TypeScript

import { randomUUID } from "node:crypto"
import { isIP } from "node:net"
import { z } from "zod"
import { routeAiProfileSchema, type RouteAiProfile } from "@mmapp/contracts/mcp-routing"
import { pool } from "../../db/index.js"
import { parsePing } from "../../services/uptime-collector.js"
import { ipv6ToInt } from "../../services/traffic-flow-ip.js"
import { fingerprint, McpError } from "./security.js"
import { readRouteCommunityContext, routeContextAccess, type RouteContextOptions } from "./routing-community-context.js"
import type { add } from "./actions.js"
import { readControlPathContext } from "./control-path-context.js"
import { COMMUNITY_PATH_MAX_AGE_MS, isCommunityPathEvidence, PATH_PROOF_VERSION, pathProofPurposeSchema, type PathProofPurpose } from "./path-proof-purpose.js"
import { routingMeasurementRefusal } from "./routing-community-predispatch-diagnostic.js"
import { connectionWrite } from "./store.js"
export function inspectControlPing(rows: Parameters<typeof parsePing>[0]) {
const parsed = parsePing(rows)
const terminal = [...rows].reverse().find(row => row.sent !== undefined || row.received !== undefined || row["packet-loss"] !== undefined || row["avg-rtt"] !== undefined)
const sent = Number(terminal?.sent), received = Number(terminal?.received)
const counts = terminal && /^\d+$/.test(terminal.sent ?? "") && /^\d+$/.test(terminal.received ?? "") && sent === 3 && Number.isSafeInteger(received) && received >= 0 && received <= sent ? { sent, received } : null
const loss = terminal?.["packet-loss"]
const malformedLoss = loss !== undefined && (!/^\d+(?:\.\d+)?%?$/.test(loss) || Number(loss.replace(/%$/, "")) > 100)
const inconsistent = !!counts && (malformedLoss || parsed.loss !== Math.round((counts.sent - counts.received) / counts.sent * 100))
const ping = !counts || inconsistent ? { ...parsed, measured: false } : parsed
const reason = !counts ? "PING_COUNTERS_UNCONFIRMED" : inconsistent ? "PING_COUNTERS_INCONSISTENT" : !ping.measured ? "PING_MEASUREMENT_UNCONFIRMED" : received > 0 && received < sent ? "PING_PARTIAL_LOSS" : null
const observedCounter = (value: string | undefined) => value !== undefined && /^\d+$/.test(value) && Number(value) <= 16 ? Number(value) : null
const observation = { rows: rows.length, hasTerminalCounters: terminal?.sent !== undefined || terminal?.received !== undefined, terminalSent: observedCounter(terminal?.sent), terminalReceived: observedCounter(terminal?.received) }
// Count is fixed at three in the command. Malformed/oversized/incomplete
// counters cannot prove success or turn an unknown probe into confirmed loss.
return { ping, packetCounts: counts, confirmedFailure: ping.measured && counts?.received === 0, reason, observation }
}
export function inspectTrace(raw: unknown, destination: string, expectedHops: string[]) {
if (!Array.isArray(raw) || !raw.length || raw.length > 256) return { verified: false, hops: [] as string[] }
let rows = raw
if (raw.some(row => row && typeof row === "object" && ".section" in row)) {
const invalidSection = raw.some(row => {
if (!row || typeof row !== "object") return true
const section = row[".section"]
if (typeof section === "number") return !Number.isInteger(section) || section < 0 || section > 99
return typeof section !== "string" || !/^\d{1,2}$/.test(section)
})
if (invalidSection) return { verified: false, hops: [] as string[] }
// RouterOS REST returns successive traceroute table snapshots. Earlier
// sections can contain unfinished empty hops; never merge them into proof.
const finalSection = Math.max(...raw.map(row => Number(row[".section"])))
rows = raw.filter(row => Number(row[".section"]) === finalSection)
}
if (rows.length > 16) return { verified: false, hops: [] as string[] }
const hops: string[] = []
let unobservedHops = 0
for (const row of rows) {
if (!row || typeof row !== "object" || row.error || row.status && row.status !== "timeout") return { verified: false, hops }
const sent = typeof row.sent === "number" || typeof row.sent === "string" && /^\d+$/.test(row.sent) ? Number(row.sent) : NaN
if (!Number.isSafeInteger(sent) || sent < 1) return { verified: false, hops }
const loss = typeof row.loss === "number" || typeof row.loss === "string" && /^\d+(?:\.\d+)?$/.test(row.loss) ? Number(row.loss) : NaN
if (!Number.isFinite(loss) || loss < 0 || loss > 100) return { verified: false, hops }
const address = typeof row.address === "string" ? row.address : row.address?.address
if (!address || row.status === "timeout") { unobservedHops++; continue }
if (typeof address !== "string" || !isIP(address.split("%")[0]) || loss !== 0) return { verified: false, hops }
hops.push(address.split("%")[0])
}
let cursor = -1
const matchesAddress = (actual: string, expected: string) => {
if (actual === expected) return true
if (expected.includes("%")) return false
const expectedV6 = ipv6ToInt(expected)
return expectedV6 !== null && ipv6ToInt(actual) === expectedV6
}
const ordered = expectedHops.every(address => {
const index = hops.findIndex((hop, index) => index > cursor && matchesAddress(hop, address))
if (index < 0) return false
cursor = index
return true
})
const last = rows.at(-1), finalAddress = typeof last?.address === "string" ? last.address : last?.address?.address
const reachedDestination = typeof finalAddress === "string" && matchesAddress(finalAddress.split("%")[0], destination)
return { verified: ordered && reachedDestination && Number(last?.loss) === 0 && !last?.status, hops, unobservedHops, completeTrace: unobservedHops === 0 }
}
export async function checkCandidatePath(profile: RouteAiProfile, candidateId: string, connectionId: string, options: RouteContextOptions & { proofPurpose?: PathProofPurpose } = {},
communityContext?: {
before: () => ReturnType<typeof readRouteCommunityContext>
after?: (options: RouteContextOptions) => ReturnType<typeof readRouteCommunityContext>
}) {
const proofPurpose = pathProofPurposeSchema.parse(options.proofPurpose ?? "community")
if (options.managementTransport && proofPurpose !== "community") throw new McpError("UNSUPPORTED_CAPABILITY", "Management transport разрешён только для Community proof", 409)
if (communityContext && proofPurpose !== "community") throw new McpError("INVALID_INPUT", "Контекст применим только к Community proof", 400)
const acquire = (sourceOptions: RouteContextOptions) => proofPurpose === "control-path" ? readControlPathContext(profile, candidateId, sourceOptions) : readRouteCommunityContext(profile, { ...sourceOptions, selectedCandidateId: candidateId })
const candidate = profile.candidates.find(candidate => candidate.id === candidateId)
if (!candidate?.controlProbe) throw new McpError("MEASUREMENT_UNKNOWN", "Для пути не настроена контрольная проверка", 409)
const probe = candidate.controlProbe, startedAt = new Date().toISOString(), id = randomUUID()
let status: "passed" | "failed" | "unknown" = "unknown", evidence: Record<string, unknown> = { startedAt }
// A recovery caller may validate its initial context as part of acquisition.
// Preserve the independent post-probe read and both probe fences.
let context: Awaited<ReturnType<typeof acquire>> | undefined = await communityContext?.before()
try {
context ??= await acquire(options)
if (!context.before.contextVerified) throw new McpError("MEASUREMENT_UNKNOWN", "Контекст контрольной проверки не подтверждён", 409)
const probeEndpoint = context.probeEndpoints.get(candidateId)
if (!probeEndpoint) throw new McpError("STATE_UNAVAILABLE", "Контекст выбранного кандидата не подтверждён", 409)
const { destination, expected, source } = probeEndpoint
if (!probe.expectedHops.some(hop => hop.serverId === candidate.jumpHostId) || probe.expectedHops.at(-1)?.serverId !== candidate.exitNodeId) throw new McpError("INVALID_INPUT", "Контрольный путь должен включать JumpHost и завершаться ExitNode", 400)
const client = context.clients.get(profile.serverId)!
const args: Record<string, string> = { address: destination, interface: candidate.wanInterface, vrf: profile.probeVrf, count: "3", interval: "0.3s" }
if (source) args["src-address"] = source
await context.fence()
const pingRaw = await client.post<unknown>("/tool/ping", args, 10000)
const pingRows = z.array(z.record(z.string(), z.string())).max(256).parse(pingRaw), { ping, packetCounts, confirmedFailure, reason, observation } = inspectControlPing(pingRows)
evidence = { ...evidence, packetCounts, pingObservation: observation, ...(reason ? { reason } : {}) }
// Only explicit terminal sent/received proves a failed check. A timeout or
// unsupported command is unknown and can never count toward failover.
if (confirmedFailure) { status = "failed"; evidence = { ...evidence, destination, ping } }
else if (ping.measured && ping.loss === 0) {
const traceArgs: Record<string, string> = { address: destination, interface: candidate.wanInterface, vrf: profile.probeVrf, count: "1", "max-hops": "16", timeout: "500ms", "use-dns": "no", protocol: "icmp" }
if (args["src-address"]) traceArgs["src-address"] = args["src-address"]
await context.fence()
const trace = inspectTrace(await client.post<unknown>("/tool/traceroute", traceArgs, 20000), destination, expected)
status = trace.verified ? "passed" : "unknown"
if (!trace.verified) evidence = { ...evidence, reason: "TRACE_UNCONFIRMED" }
evidence = { ...evidence, destination, expected, ping, trace, proofScope: "observed-control-probes-only", returnPathVerified: false }
}
const current = await (communityContext?.after ?? acquire)({ ...options, expectedSources: context.before.sourceProofs })
if (current.before.dependencyProof !== context.before.dependencyProof || current.before.targetRuleProof !== context.before.targetRuleProof) throw new McpError("STATE_CONFLICT", "Контекст пути изменился во время проверки", 409)
} catch (error) { status = "unknown"; evidence = { ...evidence, reason: error instanceof McpError ? error.code : "PROBE_UNAVAILABLE" } }
// A failed fence invalidates even an otherwise successful or failed probe.
if (["STATE_CONFLICT", "PERMISSION_DENIED", "RESET_REQUIRED", "READ_CANCELLED"].includes(String(evidence.reason))) status = "unknown"
const observedAt = new Date().toISOString()
const payload = { id, connectionId, profileHash: fingerprint(profile), candidateId, status, ...evidence, proofPurpose, proofVersion: PATH_PROOF_VERSION, proofScope: "observed-control-probes-only", returnPathVerified: false, observedAt, sourceProofs: context?.before.sourceProofs ?? [], dependencyProof: context?.before.dependencyProof ?? null }
const proof = context?.signEvidence(payload) ?? null
await connectionWrite(async client => {
await options.authorize?.()
await client.query("INSERT INTO mcp_path_checks(id,connection_id,profile_hash,candidate_id,status,evidence) VALUES($1,$2,$3,$4,$5,$6::jsonb)", [id, connectionId, payload.profileHash, candidateId, status, JSON.stringify({ ...payload, proof })])
})
return { id, candidateId, status, ...evidence, proofPurpose, proofVersion: PATH_PROOF_VERSION, proofScope: "observed-control-probes-only" as const, returnPathVerified: false, observedAt }
}
export function registerPathActions(register: typeof add) {
register("routing.path.verify", "mm_route_path_verify", "Контрольные ping и traceroute зарегистрированного пути", "network", "mm:network:read", "read", "servers", z.object({ profile: routeAiProfileSchema, candidateId: z.string().min(1), proofPurpose: pathProofPurposeSchema.default("community") }).strict(), {
target: input => { const profile = routeAiProfileSchema.parse(input.profile); return { scope: "servers", serverIds: [...new Set([profile.serverId, ...profile.candidates.flatMap(candidate => [candidate.jumpHostId, candidate.exitNodeId])])] } },
read: async (input, context) => checkCandidatePath(routeAiProfileSchema.parse(input.profile), String(input.candidateId), context.connection.id, { authorize: routeContextAccess(context), signal: context.signal, proofPurpose: pathProofPurposeSchema.parse(input.proofPurpose) }),
version: 2,
})
}
export async function requireRecentPathWithContext(profile: RouteAiProfile, candidateId: string, connectionId: string, options: RouteContextOptions = {},
acquireContext?: (options: RouteContextOptions) => ReturnType<typeof readRouteCommunityContext>) {
// Compare the database timestamp with the database clock. The signed
// observedAt below is independently checked against the application clock.
const queryStarted = performance.now()
const { rows: [row] } = await pool.query(`SELECT id,status,evidence,
EXTRACT(EPOCH FROM (clock_timestamp()-created_at))::double precision * 1000 AS database_age_ms
FROM mcp_path_checks WHERE connection_id=$1 AND profile_hash=$2 AND candidate_id=$3
AND evidence->>'proofPurpose'='community' AND evidence->>'proofVersion'='2' ORDER BY created_at DESC,id DESC LIMIT 1`, [connectionId, fingerprint(profile), candidateId])
if (!row || row.status !== "passed") throw routingMeasurementRefusal("latest-proof-unavailable", "Нет свежего подтверждения контрольного пути")
const { proof, ...evidence } = row.evidence ?? {}
if (!isCommunityPathEvidence(evidence) || evidence.id !== row.id || evidence.connectionId !== connectionId || evidence.profileHash !== fingerprint(profile) || evidence.candidateId !== candidateId || evidence.status !== "passed" || !Array.isArray(evidence.sourceProofs) || !evidence.sourceProofs.length) throw routingMeasurementRefusal("latest-proof-binding", "Подтверждение пути не связано с Community purpose, источником и контекстом")
const observedAt = Date.parse(evidence.observedAt)
const databaseAge = row.database_age_ms
const assertFresh = () => {
const signedAge = Date.now() - observedAt
// Charge the entire query duration conservatively. This also bounds the
// database clock's deadline after the last SQL read without another query.
if (!Number.isFinite(databaseAge) || databaseAge < 0 || databaseAge + performance.now() - queryStarted > COMMUNITY_PATH_MAX_AGE_MS ||
!Number.isFinite(signedAge) || signedAge < 0 || signedAge > COMMUNITY_PATH_MAX_AGE_MS)
throw routingMeasurementRefusal("latest-proof-stale", "Истёк срок подтверждения контрольного пути")
}
assertFresh()
if (options.expectedSources && fingerprint(options.expectedSources) !== fingerprint(evidence.sourceProofs)) throw new McpError("STATE_CONFLICT", "Источник контрольного пути изменился", 409)
const contextOptions = { ...options, selectedCandidateId: candidateId, expectedSources: evidence.sourceProofs }
const current = await (acquireContext ? acquireContext(contextOptions) : readRouteCommunityContext(profile, contextOptions))
if (!current.verifyEvidence(evidence, proof)) throw routingMeasurementRefusal("latest-proof-context", "Зависимости пути или сохранённое подтверждение изменились")
assertFresh()
return { id: row.id as string, context: current, assertFresh }
}
export async function requireRecentPath(profile: RouteAiProfile, candidateId: string, connectionId: string, options: RouteContextOptions = {}) {
return (await requireRecentPathWithContext(profile, candidateId, connectionId, options)).id
}