@classytic/labs 0.3.0 → 0.4.0

package/dist/networking/simulation.mjs

@@ -1,148 +0,0 @@
-import { dijkstra, reconstructPath } from "../algorithms/graph.mjs";
-
-//#region src/networking/simulation.ts
-const primaryIp = (doc, deviceId) => doc.devices.find((d) => d.id === deviceId)?.interfaces.flatMap((i) => i.addresses ?? [])[0]?.split("/")[0] ?? deviceId;
-function createPacket(doc, from, to, protocol = "icmp") {
-	const sourceIp = primaryIp(doc, from);
-	const destinationIp = primaryIp(doc, to);
-	return {
-		id: `${protocol}-${from}-${to}`,
-		from,
-		to,
-		bytes: protocol === "http" ? 428 : 84,
-		layers: [
-			{
-				kind: "application",
-				protocol: protocol === "http" ? "HTTP" : "Ping",
-				summary: protocol === "http" ? "GET / HTTP/1.1" : "Echo request"
-			},
-			{
-				kind: "transport",
-				protocol: protocol === "http" ? "TCP" : "ICMP",
-				summary: protocol === "http" ? "49152 → 80" : "type 8, code 0",
-				fields: protocol === "http" ? {
-					sourcePort: 49152,
-					destinationPort: 80
-				} : { type: 8 }
-			},
-			{
-				kind: "network",
-				protocol: "IPv4",
-				summary: `${sourceIp} → ${destinationIp}`,
-				fields: {
-					source: sourceIp,
-					destination: destinationIp,
-					ttl: 64
-				}
-			},
-			{
-				kind: "data-link",
-				protocol: "Ethernet",
-				summary: "next-hop frame (MAC addresses change each routed hop)"
-			},
-			{
-				kind: "physical",
-				protocol: "Link",
-				summary: "bits transmitted over the selected medium"
-			}
-		]
-	};
-}
-/** Small deterministic packet trace: topology/path truth is real, protocol narration is explicit. */
-function simulatePacket(doc, from, to, protocol = "icmp") {
-	const packet = createPacket(doc, from, to, protocol);
-	const upLinks = doc.links.filter((link) => link.state !== "down");
-	const path = reconstructPath(dijkstra({
-		nodes: doc.devices.map((device, index) => ({
-			id: device.id,
-			x: index,
-			y: 0
-		})),
-		edges: upLinks.map((link) => ({
-			id: link.id,
-			from: link.a.deviceId,
-			to: link.b.deviceId,
-			weight: link.cost ?? link.latencyMs ?? 1
-		}))
-	}, from, to).previous, from, to);
-	const events = [{
-		type: "packet-created",
-		at: from,
-		packet,
-		message: `${protocol.toUpperCase()} packet created at ${from}.`
-	}];
-	if (!path.length) {
-		events.push({
-			type: "packet-dropped",
-			at: from,
-			reason: "unreachable",
-			message: `No available route from ${from} to ${to}.`
-		});
-		return {
-			delivered: false,
-			path: [],
-			totalLatencyMs: 0,
-			events
-		};
-	}
-	let totalLatencyMs = 0;
-	for (let i = 0; i < path.length - 1; i++) {
-		const at = path[i];
-		const next = path[i + 1];
-		const link = upLinks.find((candidate) => candidate.a.deviceId === at && candidate.b.deviceId === next || candidate.b.deviceId === at && candidate.a.deviceId === next);
-		if (!link) continue;
-		if (i === 0) {
-			events.push({
-				type: "arp-requested",
-				at,
-				target: next,
-				message: `${at} asks for the next hop's hardware address.`
-			});
-			events.push({
-				type: "arp-resolved",
-				at,
-				target: next,
-				message: `${next} answers; ${at} can now build the Ethernet frame.`
-			});
-		}
-		const device = doc.devices.find((d) => d.id === at);
-		if (device?.kind === "router") events.push({
-			type: "route-selected",
-			at,
-			next,
-			message: `${device.label} selects the lowest-cost available next hop: ${next}.`
-		});
-		events.push({
-			type: "frame-sent",
-			at,
-			linkId: link.id,
-			next,
-			packet,
-			message: `${at} sends the frame over ${link.label ?? link.id}.`
-		});
-		totalLatencyMs += link.latencyMs ?? 1;
-		events.push({
-			type: "frame-received",
-			at: next,
-			linkId: link.id,
-			from: at,
-			packet,
-			message: `${next} receives and inspects the frame.`
-		});
-	}
-	events.push({
-		type: "packet-delivered",
-		at: to,
-		packet,
-		message: `${packet.layers[0]?.protocol ?? "Packet"} delivered to ${to} in ${totalLatencyMs} ms simulated time.`
-	});
-	return {
-		delivered: true,
-		path,
-		totalLatencyMs,
-		events
-	};
-}
-
-//#endregion
-export { createPacket, simulatePacket };

package/dist/networking/subnet.mjs

@@ -1,84 +0,0 @@
-import { ipv4ToInt } from "./ip.mjs";
-
-//#region src/networking/subnet.ts
-/**
-* Subnetting, reduced to the one question it actually answers.
-*
-* "Are these two addresses on the same network?" is the whole of it, and the answer is mechanical:
-* compare the first `prefix` bits. Same, and the two can talk directly. Different, and everything
-* has to go through a router. Every other subnetting fact (mask, network address, broadcast, usable
-* count) falls out of where that boundary sits.
-*
-* Students drown here because it is taught in dotted decimal, where the boundary is invisible. In
-* binary it is a vertical line, and the moment it crosses the first differing bit the answer flips.
-* That is the thing to show.
-*/
-const intToIpv4 = (value) => [
-	24,
-	16,
-	8,
-	0
-].map((shift) => value >>> shift & 255).join(".");
-/** The mask for a prefix, as a 32-bit unsigned value. /0 is all zeros. */
-const maskFor = (prefix) => prefix <= 0 ? 0 : prefix >= 32 ? 4294967295 : 4294967295 << 32 - prefix >>> 0;
-/** The 32 bits of an address, flagged by which side of the prefix boundary they fall. */
-function bitsOf(address, prefix) {
-	const value = ipv4ToInt(address);
-	if (value == null) return null;
-	return Array.from({ length: 32 }, (_, index) => ({
-		value: value >>> 31 - index & 1,
-		network: index < prefix
-	}));
-}
-function describe(address, prefix) {
-	const value = ipv4ToInt(address);
-	const bits = bitsOf(address, prefix);
-	if (value == null || !bits || prefix < 0 || prefix > 32) return null;
-	const mask = maskFor(prefix);
-	const network = (value & mask) >>> 0;
-	const broadcast = (network | ~mask >>> 0) >>> 0;
-	const total = 2 ** (32 - prefix);
-	const usableHosts = total > 2 ? total - 2 : 0;
-	return {
-		address,
-		prefix,
-		mask: intToIpv4(mask),
-		network: intToIpv4(network),
-		broadcast: intToIpv4(broadcast),
-		firstUsable: usableHosts ? intToIpv4(network + 1) : null,
-		lastUsable: usableHosts ? intToIpv4(broadcast - 1) : null,
-		usableHosts,
-		bits
-	};
-}
-/** Do two addresses share a network under this prefix? */
-function sameNetwork(a, b, prefix) {
-	const left = ipv4ToInt(a);
-	const right = ipv4ToInt(b);
-	if (left == null || right == null) return null;
-	const mask = maskFor(prefix);
-	return (left & mask) >>> 0 === (right & mask) >>> 0;
-}
-/**
-* The index (0-based from the left) of the first bit where two addresses differ, or -1 when they
-* are identical. This is the number the whole lab turns on: any prefix at or below it puts the two
-* on the same network, and any prefix above it separates them.
-*/
-function firstDifferingBit(a, b) {
-	const left = ipv4ToInt(a);
-	const right = ipv4ToInt(b);
-	if (left == null || right == null) return -1;
-	for (let index = 0; index < 32; index++) {
-		const shift = 31 - index;
-		if ((left >>> shift & 1) !== (right >>> shift & 1)) return index;
-	}
-	return -1;
-}
-/** The largest prefix that still keeps both addresses together. */
-function widestSharedPrefix(a, b) {
-	const differing = firstDifferingBit(a, b);
-	return differing === -1 ? 32 : differing;
-}
-
-//#endregion
-export { bitsOf, describe, firstDifferingBit, sameNetwork, widestSharedPrefix };

package/dist/networking/switch.mjs

@@ -1,155 +0,0 @@
-//#region src/networking/switch.ts
-const linkUp = (port) => port.enabled && !!port.device;
-const portOf = (state, mac) => state.table.find((entry) => entry.mac === mac)?.port;
-const deviceName = (state, mac) => state.ports.find((port) => port.device?.mac === mac)?.device?.name ?? mac;
-/**
-* Send one frame in through `fromPort` and resolve what the switch does with it.
-*
-* Pure: returns the next state rather than mutating, so a lesson can step forward and back.
-*/
-function sendFrame(state, fromPort, dstMac) {
-	const events = [];
-	const ingress = state.ports.find((port) => port.id === fromPort);
-	const srcMac = ingress?.device?.mac ?? "";
-	if (!ingress || !ingress.enabled) {
-		events.push({
-			type: "drop",
-			reason: "port-down",
-			message: `Port ${fromPort} is disabled, so nothing can enter through it.`
-		});
-		return {
-			events,
-			next: state,
-			delivered: [],
-			flooded: false
-		};
-	}
-	if (!ingress.device) {
-		events.push({
-			type: "drop",
-			reason: "no-link",
-			message: `Port ${fromPort} has nothing plugged into it.`
-		});
-		return {
-			events,
-			next: state,
-			delivered: [],
-			flooded: false
-		};
-	}
-	events.push({
-		type: "ingress",
-		port: fromPort,
-		srcMac,
-		dstMac,
-		message: `A frame from ${ingress.device.name} arrives on port ${fromPort}, addressed to ${deviceName(state, dstMac)}.`
-	});
-	const known = state.table.find((entry) => entry.mac === srcMac);
-	const relearned = !!known && known.port !== fromPort;
-	const table = [...state.table.filter((entry) => entry.mac !== srcMac), {
-		mac: srcMac,
-		port: fromPort
-	}].sort((a, b) => a.port - b.port || a.mac.localeCompare(b.mac));
-	if (!known || relearned) events.push({
-		type: "learn",
-		mac: srcMac,
-		port: fromPort,
-		relearned,
-		message: relearned ? `${ingress.device.name} has moved. The table now says port ${fromPort}.` : `Learned: ${ingress.device.name} is reachable through port ${fromPort}.`
-	});
-	const next = {
-		ports: state.ports,
-		table
-	};
-	const target = portOf(next, dstMac);
-	if (target === fromPort) {
-		events.push({
-			type: "drop",
-			reason: "same-port",
-			message: `The destination is on the port the frame arrived from, so the switch does not send it back out.`
-		});
-		return {
-			events,
-			next,
-			delivered: [],
-			flooded: false
-		};
-	}
-	if (target !== void 0 && linkUp(state.ports.find((port) => port.id === target))) {
-		events.push({
-			type: "forward",
-			port: target,
-			message: `The table knows this address, so the frame goes out of port ${target} only. No other device sees it.`
-		});
-		return {
-			events,
-			next,
-			delivered: [target],
-			flooded: false
-		};
-	}
-	const flooded = next.ports.filter((port) => port.id !== fromPort && linkUp(port)).map((port) => port.id);
-	events.push({
-		type: "flood",
-		ports: flooded,
-		message: flooded.length ? `This address is not in the table, so the switch floods: out of every connected port except ${fromPort}.` : `This address is not in the table, and no other port has a link, so there is nowhere to flood.`
-	});
-	return {
-		events,
-		next,
-		delivered: flooded,
-		flooded: true
-	};
-}
-/** Toggle a port up or down. A port going down forgets what was learned through it. */
-function setPortEnabled(state, portId, enabled) {
-	return {
-		ports: state.ports.map((port) => port.id === portId ? {
-			...port,
-			enabled
-		} : port),
-		table: enabled ? state.table : state.table.filter((entry) => entry.port !== portId)
-	};
-}
-/** Clear the forwarding table, which returns the switch to the day it was unboxed. */
-const clearTable = (state) => ({
-	ports: state.ports,
-	table: []
-});
-const MACS = [
-	"AA:01",
-	"BB:02",
-	"CC:03",
-	"DD:04",
-	"EE:05",
-	"FF:06",
-	"11:07",
-	"22:08"
-];
-const NAMES = [
-	"Laptop",
-	"Desktop",
-	"Printer",
-	"Server",
-	"Phone",
-	"Camera",
-	"NAS",
-	"TV"
-];
-/** A switch with `size` ports, the first `connected` of them holding a device. */
-function makeSwitch(size = 8, connected = 4) {
-	return {
-		ports: Array.from({ length: size }, (_, index) => ({
-			id: index + 1,
-			enabled: true,
-			device: index < connected ? {
-				name: NAMES[index],
-				mac: MACS[index]
-			} : void 0
-		})),
-		table: []
-	};
-}
-
-//#endregion
-export { clearTable, linkUp, makeSwitch, sendFrame, setPortEnabled };

package/dist/networking/vlan.mjs

@@ -1,100 +0,0 @@
-//#region src/networking/vlan.ts
-const isLive = (port) => port.enabled && !!port.device;
-/** Ports in the same VLAN as `portId`, excluding itself. */
-function domainOf(state, portId) {
-	const source = state.ports.find((port) => port.id === portId);
-	if (!source) return [];
-	return state.ports.filter((port) => port.id !== portId && port.vlan === source.vlan && isLive(port)).map((port) => port.id);
-}
-/** A broadcast reaches its own VLAN and stops there. Routing does not change that. */
-function broadcastFrom(state, portId) {
-	const source = state.ports.find((port) => port.id === portId);
-	if (!source || !isLive(source)) return {
-		reached: [],
-		blocked: [],
-		message: `Port ${portId} has no live device to send from.`
-	};
-	const reached = domainOf(state, portId);
-	const blocked = state.ports.filter((port) => port.id !== portId && isLive(port) && port.vlan !== source.vlan).map((port) => port.id);
-	const vlanName = state.vlans.find((vlan) => vlan.id === source.vlan)?.name ?? `VLAN ${source.vlan}`;
-	return {
-		reached,
-		blocked,
-		message: blocked.length ? `The broadcast reaches every live port in ${vlanName} and stops. ${blocked.length} live port${blocked.length > 1 ? "s are" : " is"} in another VLAN and never sees it.` : `The broadcast reaches every live port in ${vlanName}.`
-	};
-}
-/**
-* Directed traffic between two ports. Within a VLAN the switch forwards it. Across VLANs it needs
-* a layer-3 interface, and that interface is where a policy would sit.
-*/
-function sendBetween(state, fromPort, toPort) {
-	const source = state.ports.find((port) => port.id === fromPort);
-	const target = state.ports.find((port) => port.id === toPort);
-	if (!source || !target || !isLive(source) || !isLive(target)) return {
-		delivered: false,
-		viaRouter: false,
-		message: "Both ends need a live device."
-	};
-	if (source.vlan === target.vlan) return {
-		delivered: true,
-		viaRouter: false,
-		message: `Same VLAN, so the switch forwards it directly. Nothing outside the VLAN is involved.`
-	};
-	if (!state.routing) return {
-		delivered: false,
-		viaRouter: false,
-		message: `Different VLANs and no layer-3 interface, so there is no path at all. The switch will not carry it.`
-	};
-	return {
-		delivered: true,
-		viaRouter: true,
-		message: `Different VLANs, so it goes up to the layer-3 interface and back down. Every crossing passes that one point, which is where a rule can be applied.`
-	};
-}
-function setPortVlan(state, portId, vlan) {
-	return {
-		...state,
-		ports: state.ports.map((port) => port.id === portId ? {
-			...port,
-			vlan
-		} : port)
-	};
-}
-const setRouting = (state, routing) => ({
-	...state,
-	routing
-});
-/** How many separate broadcast domains this switch is currently carrying. */
-const domainCount = (state) => new Set(state.ports.filter(isLive).map((port) => port.vlan)).size;
-const NAMES = [
-	"Sales",
-	"Finance",
-	"Reception",
-	"Store",
-	"Server A",
-	"Server B",
-	"Kiosk",
-	"Camera"
-];
-/** Eight ports, the first `connected` holding a device, split evenly across two VLANs. */
-function makeVlanSwitch(connected = 6) {
-	return {
-		vlans: [{
-			id: 10,
-			name: "VLAN 10"
-		}, {
-			id: 20,
-			name: "VLAN 20"
-		}],
-		routing: false,
-		ports: Array.from({ length: 8 }, (_, index) => ({
-			id: index + 1,
-			vlan: index < 4 ? 10 : 20,
-			enabled: true,
-			device: index < connected ? { name: NAMES[index] } : void 0
-		}))
-	};
-}
-
-//#endregion
-export { broadcastFrom, domainCount, isLive, makeVlanSwitch, sendBetween, setPortVlan, setRouting };

package/dist/networking/vpn.mjs

@@ -1,118 +0,0 @@
-//#region src/networking/vpn.ts
-const OBSERVERS = [
-	{
-		id: "wifi",
-		name: "The café Wi-Fi",
-		short: "Café Wi-Fi",
-		where: "anyone else on the same network, including whoever runs it"
-	},
-	{
-		id: "isp",
-		name: "Your internet provider",
-		short: "Your provider",
-		where: "every packet you send crosses their equipment"
-	},
-	{
-		id: "gateway",
-		name: "The VPN provider",
-		short: "VPN provider",
-		where: "the far end of the tunnel, where the wrapping comes off"
-	},
-	{
-		id: "website",
-		name: "The website",
-		short: "The website",
-		where: "the machine you are actually talking to"
-	}
-];
-const YOU = "You";
-const GATEWAY = "VPN gateway";
-const SITE = "example.com";
-const CIPHER = "unreadable";
-/** Watchers that exist in this setup. Without a tunnel there is no gateway to watch. */
-const observersFor = (setup) => OBSERVERS.filter((observer) => observer.id !== "gateway" || setup.vpn);
-function observe(id, setup) {
-	const observer = OBSERVERS.find((item) => item.id === id);
-	if (!observer || id === "gateway" && !setup.vpn) return null;
-	if (id === "website") return {
-		observer,
-		from: {
-			value: setup.vpn ? GATEWAY : YOU,
-			hidden: false
-		},
-		to: {
-			value: SITE,
-			hidden: false
-		},
-		contents: {
-			value: "your request, in full",
-			hidden: false
-		},
-		verdict: setup.vpn ? "Sees a request arriving from the VPN gateway rather than from you, and reads it in full. It has to: it is the one answering." : "Sees your own address and reads the request in full. HTTPS protects it from everyone in between, never from the far end."
-	};
-	if (setup.vpn) {
-		if (id === "gateway") return {
-			observer,
-			from: {
-				value: YOU,
-				hidden: false
-			},
-			to: {
-				value: SITE,
-				hidden: false
-			},
-			contents: setup.https ? {
-				value: CIPHER,
-				hidden: true
-			} : {
-				value: "your request, in full",
-				hidden: false
-			},
-			verdict: setup.https ? "Knows who you are and every site you ask for, but HTTPS still keeps the contents from them. This is the trade: your provider stopped seeing this and they started." : "Knows who you are, every site you ask for, and everything you send. Without HTTPS you have simply changed which company watches you."
-		};
-		return {
-			observer,
-			from: {
-				value: YOU,
-				hidden: false
-			},
-			to: {
-				value: GATEWAY,
-				hidden: false
-			},
-			contents: {
-				value: CIPHER,
-				hidden: true
-			},
-			verdict: "Can tell you are using a VPN and nothing else. Which sites you visit is inside the wrapping, so it is not available here at any price."
-		};
-	}
-	return {
-		observer,
-		from: {
-			value: YOU,
-			hidden: false
-		},
-		to: {
-			value: SITE,
-			hidden: false
-		},
-		contents: setup.https ? {
-			value: CIPHER,
-			hidden: true
-		} : {
-			value: "your request, in full",
-			hidden: false
-		},
-		verdict: setup.https ? "Sees which sites you visit and when, but not what you asked for or what came back." : "Sees which sites you visit and can read every word of it."
-	};
-}
-/** Every watcher's view of one setup, which is where the pattern shows up. */
-const surveyOf = (setup) => observersFor(setup).map((observer) => observe(observer.id, setup)).filter((sighting) => sighting !== null);
-/** Watchers who can name the site being visited. The count is the honest summary of a setup. */
-const canSeeDestination = (setup) => surveyOf(setup).filter((sighting) => !sighting.to.hidden && sighting.to.value === SITE).map((sighting) => sighting.observer.id);
-/** Watchers who can read what you actually sent. */
-const canReadContents = (setup) => surveyOf(setup).filter((sighting) => !sighting.contents.hidden).map((sighting) => sighting.observer.id);
-
-//#endregion
-export { OBSERVERS, canReadContents, canSeeDestination, observe, observersFor };