Files
MikrotikManager/backend/src/services/bandwidth-peer-network-observation.ts
T

175 lines
15 KiB
TypeScript

/** Genuine read-only management observations, never proof of the actual wire
* destination, effective NAT path, DNS resolution or clone resistance. Native
* catalogues are untrusted data; only this reader's opaque token has provenance. */
import { isDeepStrictEqual } from "node:util"
import { performance } from "node:perf_hooks"
import { createBandwidthPeerObservationReader, type BandwidthPeerTrustedSource, type BandwidthPeerSourceSnapshot, type BandwidthPeerObservationEvidence } from "./bandwidth-peer-observation.js"
import { parseBandwidthPeerRef, bandwidthPeerRefKey, type BandwidthPeerRef } from "./bandwidth-peer-reference.js"
import type { BandwidthNodeObservationScope } from "./bandwidth-node-observation.js"
const paths = ["/ip/address", "/ipv6/address", "/interface", "/ip/vrf", "/routing/table", "/routing/route", "/routing/rule", "/ip/firewall/nat", "/ip/firewall/mangle", "/ipv6/firewall/mangle", "/interface/list", "/interface/list/member"] as const
type Resource = typeof paths[number]
type Fact = string | number | boolean | null | readonly Fact[]
type Row = Readonly<Record<string, Fact>>
const common = [".id", "disabled", "invalid", "dynamic"]
const policy = ["chain", "action", "src-address", "dst-address", "src-address-list", "dst-address-list", "src-port", "dst-port", "protocol", "in-interface", "out-interface", "in-interface-list", "out-interface-list", "routing-mark", "connection-mark", "connection-state", "connection-nat-state", "connection-type", "connection-bytes", "connection-rate", "connection-limit", "connection-pcc", "per-connection-classifier", "src-address-type", "dst-address-type", "src-mac-address", "to-addresses", "to-ports", "jump-target", "new-routing-mark", "new-connection-mark", "new-packet-mark", "passthrough", "hotspot", "ipsec-policy", "packet-mark", "packet-size", "fragment", "tcp-flags", "time", "random", "nth", "psd", "limit", "dst-limit", "layer7-protocol", "content", "tls-host", "log", "log-prefix"]
const fields: Record<Resource, ReadonlySet<string>> = {
"/ip/address": new Set([...common, "address", "network", "interface", "actual-interface"]),
"/ipv6/address": new Set([...common, "address", "interface", "actual-interface", "advertise", "from-pool", "no-dad"]),
"/interface": new Set([...common, "name", "type", "running", "slave", "mtu", "actual-mtu", "l2mtu", "mac-address", "default-name"]),
"/ip/vrf": new Set([...common, "name", "interfaces", "routing-table"]),
"/routing/table": new Set([...common, "name", "fib"]),
"/routing/route": new Set([...common, "dst-address", "gateway", "immediate-gw", "routing-table", "vrf-interface", "active", "unreachable", "blackhole", "distance", "scope", "target-scope", "local-address", "pref-src", "belongs-to", "routing-mark"]),
"/routing/rule": new Set([...common, "src-address", "dst-address", "interface", "routing-mark", "action", "table", "min-prefix", "suppress-prefixlength"]),
"/ip/firewall/nat": new Set([...common, ...policy]),
"/ip/firewall/mangle": new Set([...common, ...policy]),
"/ipv6/firewall/mangle": new Set([...common, ...policy]),
"/interface/list": new Set([...common, "name", "include", "exclude"]),
"/interface/list/member": new Set([...common, "list", "interface"]),
}
declare const networkBrand: unique symbol
export type BandwidthPeerNetworkObservation = Readonly<{ kind: "routeros-peer-network-observation"; [networkBrand]: true }>
export interface BandwidthPeerNetworkCatalogue {
readonly resource: Resource
readonly observedAt: number
readonly rows: readonly Row[]
/** Original response order is retained, including ordered VRF/NAT rules. */
readonly omittedFields: readonly (readonly string[])[]
readonly allRowsCaptured: true
readonly semanticsVerified: false
}
export interface BandwidthPeerNetworkEvidence {
readonly version: 1
readonly identity: Readonly<BandwidthPeerObservationEvidence>
readonly observedAt: number
readonly expiresAt: number
readonly catalogues: readonly BandwidthPeerNetworkCatalogue[]
readonly mappingVerified: false
readonly dnsResolverFenceVerified: false
readonly natPathCoverageVerified: false
}
export class BandwidthPeerNetworkObservationError extends Error {
constructor(readonly code: "INVALID_INPUT" | "CANCELLED" | "CLOSED" | "SOURCE_CHANGED" | "SOURCE_UNAVAILABLE" | "INVALID_NATIVE_RESPONSE" | "NOT_GENUINE") { super("Bandwidth peer network observation: " + code) }
}
const fail = (code: BandwidthPeerNetworkObservationError["code"]): never => { throw new BandwidthPeerNetworkObservationError(code) }
const plain = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype
function own(value: unknown): Record<string, PropertyDescriptor> {
if (!plain(value)) return fail("INVALID_INPUT")
const descriptors = Object.getOwnPropertyDescriptors(value)
if (Reflect.ownKeys(value).length !== Object.keys(descriptors).length || Object.values(descriptors).some(item => !("value" in item) || !item.enumerable)) fail("INVALID_INPUT")
return descriptors
}
function sourceSnapshot(raw: unknown, peer: BandwidthPeerRef): Readonly<BandwidthPeerSourceSnapshot> {
const source = own(raw), endpoint = own(source.endpoint?.value)
if (Object.keys(source).sort().join() !== "authorityGeneration,enabled,endpoint,peerRef,sourceProof" || Object.keys(endpoint).sort().join() !== "host,password,port,routingEndpointEpoch,useSsl,username,verifySsl") fail("SOURCE_UNAVAILABLE")
const value = Object.fromEntries(Object.entries(source).map(([key, item]) => [key, item.value])) as unknown as BandwidthPeerSourceSnapshot
const copied = Object.fromEntries(Object.entries(endpoint).map(([key, item]) => [key, item.value])) as unknown as BandwidthPeerSourceSnapshot["endpoint"]
const ref = parseBandwidthPeerRef(value.peerRef)
if (bandwidthPeerRefKey(ref) !== bandwidthPeerRefKey(peer) || value.enabled !== true || typeof value.sourceProof !== "string" || !/^[a-f0-9]{64}$/.test(value.sourceProof)
|| typeof value.authorityGeneration !== "string" || !value.authorityGeneration.length || Buffer.byteLength(value.authorityGeneration) > 200
|| typeof copied.host !== "string" || !copied.host.length || Buffer.byteLength(copied.host) > 1000 || /[\s/\\\u0000-\u001f\u007f]/.test(copied.host)
|| !Number.isSafeInteger(copied.port) || copied.port < 1 || copied.port > 65535 || typeof copied.useSsl !== "boolean" || typeof copied.verifySsl !== "boolean"
|| typeof copied.username !== "string" || Buffer.byteLength(copied.username) > 1000 || typeof copied.password !== "string" || Buffer.byteLength(copied.password) > 65536
|| typeof copied.routingEndpointEpoch !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(copied.routingEndpointEpoch)) fail("SOURCE_UNAVAILABLE")
return Object.freeze({ peerRef: ref, enabled: true, sourceProof: value.sourceProof, authorityGeneration: value.authorityGeneration, endpoint: Object.freeze(copied) })
}
function catalogue(resource: Resource, raw: unknown, observedAt: number, budget: { rows: number; bytes: number }): BandwidthPeerNetworkCatalogue {
if (!Array.isArray(raw) || raw.length > 2048 || Reflect.ownKeys(raw).length !== raw.length + 1) return fail("INVALID_NATIVE_RESPONSE")
const result: Row[] = [], omitted: string[][] = []
const fact = (value: unknown, depth = 0): Fact => {
if (depth > 2) return fail("INVALID_NATIVE_RESPONSE")
if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return value
if (typeof value === "string" && Buffer.byteLength(value) <= 8192) return value
if (Array.isArray(value) && value.length <= 64 && Reflect.ownKeys(value).length === value.length + 1) return Object.freeze(value.map(item => fact(item, depth + 1)))
return fail("INVALID_NATIVE_RESPONSE")
}
for (const row of raw) {
if (!plain(row) || Reflect.ownKeys(row).length > 128) fail("INVALID_NATIVE_RESPONSE")
const descriptors = own(row), projected: Record<string, Fact> = {}, missing: string[] = []
if (++budget.rows > 4096) fail("INVALID_NATIVE_RESPONSE")
for (const [key, item] of Object.entries(descriptors)) {
if (Buffer.byteLength(key) > 128 || key === "__proto__") fail("INVALID_NATIVE_RESPONSE")
// Validate all values before projecting; malformed unknown properties do
// not become a trustworthy complete catalogue by being discarded.
const value = fact(item.value)
budget.bytes += Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(value))
if (budget.bytes > 1048576) fail("INVALID_NATIVE_RESPONSE")
if (fields[resource].has(key)) Object.defineProperty(projected, key, { value, enumerable: true })
else missing.push(key)
}
result.push(Object.freeze(projected)); omitted.push(Object.freeze(missing.sort()) as string[])
}
return Object.freeze({ resource, observedAt, rows: Object.freeze(result), omittedFields: Object.freeze(omitted), allRowsCaptured: true, semanticsVerified: false })
}
type Origin = { source: Readonly<BandwidthPeerSourceSnapshot>; evidence: Readonly<BandwidthPeerNetworkEvidence>; monotonicEnd: number; signal?: AbortSignal }
export function createBandwidthPeerNetworkObservationReader(trustedSource: BandwidthPeerTrustedSource) {
if (!trustedSource || typeof trustedSource.read !== "function") fail("INVALID_INPUT")
const read = trustedSource.read.bind(trustedSource), licenses = createBandwidthPeerObservationReader(Object.freeze({ read })), observations = new WeakMap<object, Origin>(), windows = new Set<AbortController>()
let closed = false
const active = () => { if (closed) fail("CLOSED") }
function window(raw: BandwidthNodeObservationScope, origin?: Origin) {
active(); const descriptors = own(raw)
if (Object.keys(descriptors).some(key => !["deadlineAt", "signal"].includes(key))) fail("INVALID_INPUT")
const deadline = descriptors.deadlineAt?.value as number, external = descriptors.signal?.value as AbortSignal | undefined
if (!Number.isSafeInteger(deadline) || external !== undefined && !(external instanceof AbortSignal)) fail("INVALID_INPUT")
const wall = Date.now(), mono = performance.now(), duration = Math.min(5000, deadline - wall, origin ? origin.evidence.expiresAt - wall : Infinity, origin ? origin.monotonicEnd - mono : Infinity)
if (duration <= 0 || external?.aborted || origin?.signal?.aborted) fail("CANCELLED")
const deadlineAt = Math.min(deadline, wall + Math.floor(duration), origin?.evidence.expiresAt ?? Infinity), monotonicEnd = mono + duration, controller = new AbortController()
const abort = () => controller.abort(), timer = setTimeout(abort, Math.max(1, Math.ceil(duration)))
windows.add(controller); external?.addEventListener("abort", abort, { once: true }); origin?.signal?.addEventListener("abort", abort, { once: true })
const live = () => { active(); if (controller.signal.aborted || external?.aborted || origin?.signal?.aborted || Date.now() >= deadlineAt || performance.now() >= monotonicEnd) fail("CANCELLED") }
const scope = Object.freeze({ deadlineAt, signal: controller.signal })
const wait = async <T>(work: () => Promise<T>): Promise<T> => {
live(); let reject!: () => void
const cancelled = new Promise<never>((_resolve, denied) => { reject = () => denied(new BandwidthPeerNetworkObservationError("CANCELLED")); controller.signal.addEventListener("abort", reject, { once: true }) })
try { const value = await Promise.race([Promise.resolve().then(() => { live(); return work() }), cancelled]); live(); return value }
finally { controller.signal.removeEventListener("abort", reject) }
}
return { scope, live, wait, monotonicEnd, external, dispose() { clearTimeout(timer); external?.removeEventListener("abort", abort); origin?.signal?.removeEventListener("abort", abort); windows.delete(controller); controller.abort() } }
}
return Object.freeze({
async observe(rawPeer: BandwidthPeerRef, scope: BandwidthNodeObservationScope): Promise<BandwidthPeerNetworkObservation> {
const peer = parseBandwidthPeerRef(rawPeer), owned = window(scope)
try {
const before = sourceSnapshot(await owned.wait(() => read(peer, owned.scope)), peer)
const fresh = async () => { if (!isDeepStrictEqual(sourceSnapshot(await owned.wait(() => read(peer, owned.scope)), peer), before)) fail("SOURCE_CHANGED") }
const identityToken = await owned.wait(() => licenses.observe(peer, owned.scope)); await fresh()
const identity = await owned.wait(() => licenses.inspect(identityToken, owned.scope)); await fresh()
const { MikrotikClient } = await owned.wait(() => import("./mikrotik.js")); await fresh()
const client = new MikrotikClient(before.endpoint), catalogues: BandwidthPeerNetworkCatalogue[] = [], budget = { rows: 0, bytes: 0 }
// Fixed full responses, no .proplist/filter/limit or pagination that
// silently turns omitted rules into absence. Catalogue wire bound <=1.5MiB.
for (const resource of paths) {
await fresh()
const rows = await owned.wait(() => client.get<unknown>(resource, Math.max(1, owned.scope.deadlineAt - Date.now()), owned.scope.signal, 131072, fresh))
const observedAt = Date.now()
await fresh(); catalogues.push(catalogue(resource, rows, observedAt, budget)); owned.live()
}
// A fixed management endpoint can begin serving another router without
// its stored credentials/epoch changing. Bracket catalogues with a
// second genuine license GET, under the ORIGINAL operation budget.
const afterToken = await owned.wait(() => licenses.observe(peer, owned.scope)); await fresh()
const afterIdentity = await owned.wait(() => licenses.inspect(afterToken, owned.scope)); await fresh()
const { observedAt: _beforeAt, expiresAt: _beforeExpiry, ...beforeSubject } = identity
const { observedAt: _afterAt, expiresAt: _afterExpiry, ...afterSubject } = afterIdentity
if (!isDeepStrictEqual(beforeSubject, afterSubject)) fail("SOURCE_CHANGED")
const evidence = Object.freeze({ version: 1 as const, identity, observedAt: Date.now(), expiresAt: Math.min(owned.scope.deadlineAt, identity.expiresAt), catalogues: Object.freeze(catalogues), mappingVerified: false as const, dnsResolverFenceVerified: false as const, natPathCoverageVerified: false as const })
const token = Object.freeze({ kind: "routeros-peer-network-observation" as const }) as BandwidthPeerNetworkObservation
observations.set(token, { source: before, evidence, monotonicEnd: owned.monotonicEnd, signal: owned.external }); return token
} catch (error) { if (error instanceof BandwidthPeerNetworkObservationError) throw error; throw new BandwidthPeerNetworkObservationError("SOURCE_UNAVAILABLE") }
finally { owned.dispose() }
},
async inspect(token: unknown, scope: BandwidthNodeObservationScope): Promise<Readonly<BandwidthPeerNetworkEvidence>> {
active(); const origin = token && typeof token === "object" ? observations.get(token) : undefined
if (!origin) return fail("NOT_GENUINE")
const owned = window(scope, origin)
try {
if (!isDeepStrictEqual(sourceSnapshot(await owned.wait(() => read(origin.source.peerRef, owned.scope)), origin.source.peerRef), origin.source)) fail("SOURCE_CHANGED")
owned.live(); return origin.evidence
} catch (error) { if (error instanceof BandwidthPeerNetworkObservationError) throw error; throw new BandwidthPeerNetworkObservationError("SOURCE_UNAVAILABLE") }
finally { owned.dispose() }
},
close() { closed = true; licenses.close(); for (const controller of windows) controller.abort() },
})
}