175 lines
15 KiB
TypeScript
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() },
|
|
})
|
|
}
|