@braedonsaunders/appkit-desk 0.7.0 → 0.8.0

package/port-relay.js

@@ -0,0 +1,56 @@
+import { createServer } from 'node:net';
+import { DeskError } from './plan.js';
+/** Expose one guest TCP port to local HTTP, WebSocket or other TCP clients. */
+export async function listenDeskPort(desk, port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new DeskError('Guest TCP port must be between 1 and 65535.');
+    const clients = new Set();
+    const guests = new Set();
+    let closed = false;
+    let closing;
+    const server = createServer((client) => {
+        if (closed) {
+            client.destroy();
+            return;
+        }
+        clients.add(client);
+        client.once('close', () => clients.delete(client));
+        client.on('error', () => client.destroy());
+        void Promise.resolve().then(() => desk.connect(port)).then((guest) => {
+            if (closed || client.destroyed) {
+                guest.destroy();
+                return;
+            }
+            guests.add(guest);
+            guest.once('close', () => { guests.delete(guest); client.destroy(); });
+            guest.on('error', () => { guest.destroy(); client.destroy(); });
+            client.once('close', () => guest.destroy());
+            client.pipe(guest).pipe(client);
+        }, () => client.destroy());
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => reject(error);
+        server.once('error', onError);
+        server.listen(0, '127.0.0.1', () => { server.off('error', onError); resolve(); });
+    });
+    // Errors after listen must not become unhandled process errors.
+    server.on('error', () => { void close(); });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        server.close();
+        throw new DeskError('Could not determine desk relay address.');
+    }
+    function close() {
+        if (closing)
+            return closing;
+        closed = true;
+        for (const client of clients)
+            client.destroy();
+        for (const guest of guests)
+            guest.destroy();
+        closing = new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+        return closing;
+    }
+    return { host: '127.0.0.1', port: address.port, close };
+}
+//# sourceMappingURL=port-relay.js.map

package/port-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-relay.js","sourceRoot":"","sources":["../src/port-relay.ts"],"names":[],"mappings":"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","sourcesContent":["import { createServer, type Server, type Socket } from 'node:net'\nimport type { Duplex } from 'node:stream'\nimport { DeskError } from './plan'\n\n/** A local endpoint backed by a running desk's TCP connection. */\nexport interface DeskPortListener {\n  host: '127.0.0.1'\n  port: number\n  /** Close the listener and every active connection. Safe to call repeatedly. */\n  close(): Promise<void>\n}\n\n/** Expose one guest TCP port to local HTTP, WebSocket or other TCP clients. */\nexport async function listenDeskPort(\n  desk: { connect(port: number): Promise<Duplex> },\n  port: number,\n): Promise<DeskPortListener> {\n  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new DeskError('Guest TCP port must be between 1 and 65535.')\n  const clients = new Set<Socket>()\n  const guests = new Set<Duplex>()\n  let closed = false\n  let closing: Promise<void> | undefined\n  const server: Server = createServer((client) => {\n    if (closed) { client.destroy(); return }\n    clients.add(client)\n    client.once('close', () => clients.delete(client))\n    client.on('error', () => client.destroy())\n    void Promise.resolve().then(() => desk.connect(port)).then((guest) => {\n      if (closed || client.destroyed) { guest.destroy(); return }\n      guests.add(guest)\n      guest.once('close', () => { guests.delete(guest); client.destroy() })\n      guest.on('error', () => { guest.destroy(); client.destroy() })\n      client.once('close', () => guest.destroy())\n      client.pipe(guest).pipe(client)\n    }, () => client.destroy())\n  })\n  await new Promise<void>((resolve, reject) => {\n    const onError = (error: Error) => reject(error)\n    server.once('error', onError)\n    server.listen(0, '127.0.0.1', () => { server.off('error', onError); resolve() })\n  })\n  // Errors after listen must not become unhandled process errors.\n  server.on('error', () => { void close() })\n  const address = server.address()\n  if (!address || typeof address === 'string') { server.close(); throw new DeskError('Could not determine desk relay address.') }\n  function close(): Promise<void> {\n    if (closing) return closing\n    closed = true\n    for (const client of clients) client.destroy()\n    for (const guest of guests) guest.destroy()\n    closing = new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))\n    return closing\n  }\n  return { host: '127.0.0.1', port: address.port, close }\n}\n"]}

package/virtualization.d.ts

@@ -0,0 +1,16 @@
+import type { Duplex } from 'node:stream';
+import type { DeskBackend, DeskProcessLauncher } from './backend.js';
+/** A signed helper is supplied by the host; it is not downloaded or executed at install time. */
+export interface VirtualizationBackendOptions {
+    helperPath: string;
+    launcher?: DeskProcessLauncher;
+    connect?: (socketPath: string) => Duplex;
+    connectTimeoutMs?: number;
+    /** Existing file for the guest serial console; omit to disable it. */
+    consoleLogPath?: string;
+    requestTimeoutMs?: number;
+    guestAgentPort?: number;
+    platform?: NodeJS.Platform;
+}
+export declare function createVirtualizationBackend(options: VirtualizationBackendOptions): DeskBackend;
+//# sourceMappingURL=virtualization.d.ts.map

package/virtualization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualization.d.ts","sourceRoot":"","sources":["../src/virtualization.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAQjE,iGAAiG;AACjG,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;CAC3B;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,WAAW,CAmG9F"}

package/virtualization.js

@@ -0,0 +1,148 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { DeskError } from './plan.js';
+import { GUEST_AGENT_VSOCK_PORT } from './protocol.js';
+import { attemptHandshake, connectWithRetry, createGuestMachine, defaultConnect, drainOutput, errorMessage, runToCompletion, terminate, watchExit, } from './machine.js';
+export function createVirtualizationBackend(options) {
+    if (options.consoleLogPath && !isAbsolute(options.consoleLogPath))
+        throw new DeskError('consoleLogPath must be an absolute path.');
+    if (!isAbsolute(options.helperPath))
+        throw new DeskError('helperPath must be an absolute path.');
+    const launcher = options.launcher ?? ((command, args, { identity }) => spawn(command, [...args], {
+        stdio: ['pipe', 'pipe', 'pipe'], uid: identity?.uid, gid: identity?.gid,
+    }));
+    const timeout = options.connectTimeoutMs ?? 30_000;
+    return {
+        hypervisor: 'virtualization',
+        vmmPath: options.helperPath,
+        async boot(plan, hooks) {
+            if (plan.hypervisor !== 'virtualization')
+                throw new DeskError('Virtualization backend requires a virtualization plan.');
+            if ((options.platform ?? process.platform) !== 'darwin')
+                throw new DeskError('Virtualization requires macOS.');
+            if (plan.overlay.create)
+                await runToCompletion(launcher(plan.overlay.create.command, plan.overlay.create.args, { identity: plan.launcherIdentity }), `overlay creation for desk ${plan.deskId}`);
+            await mkdir(dirname(plan.vsock.socketPath), { recursive: true, mode: 0o700 });
+            const child = launcher(options.helperPath, [], { identity: plan.launcherIdentity });
+            const exit = watchExit(child);
+            const log = drainOutput(child, 8192, ['stderr']);
+            if (!child.stdin || !child.stdout) {
+                await terminate(child, exit, 2000);
+                throw new DeskError('Virtualization helper requires piped stdin and stdout.');
+            }
+            const input = child.stdin;
+            // A helper exit may close stdin while a write is in flight.
+            input.on('error', () => undefined);
+            const pending = new Map();
+            const lines = createInterface({ input: child.stdout });
+            lines.on('line', (line) => {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (!message || typeof message !== 'object' || typeof message.id !== 'string')
+                    return;
+                const entry = pending.get(message.id);
+                if (!entry)
+                    return;
+                pending.delete(message.id);
+                clearTimeout(entry.timer);
+                if (message.ok === true && message.result && typeof message.result === 'object')
+                    entry.resolve(message.result);
+                else
+                    entry.reject(new DeskError(String(message.error ?? 'Helper request failed.')));
+            });
+            void exit.promise.then(() => {
+                for (const entry of pending.values()) {
+                    clearTimeout(entry.timer);
+                    entry.reject(new DeskError(`Virtualization helper exited: ${log.tail()}`));
+                }
+                pending.clear();
+                lines.close();
+            });
+            function call(op, fields = {}) {
+                if (exit.done)
+                    return Promise.reject(new DeskError('Virtualization helper exited.'));
+                const id = randomUUID();
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { pending.delete(id); reject(new DeskError(`Virtualization helper ${op} timed out.`)); }, timeout);
+                    pending.set(id, { resolve, reject, timer });
+                    input.write(`${JSON.stringify({ ...fields, id, op })}\n`, (error) => {
+                        if (error) {
+                            const entry = pending.get(id);
+                            if (entry) {
+                                clearTimeout(entry.timer);
+                                pending.delete(id);
+                                reject(error);
+                            }
+                        }
+                    });
+                });
+            }
+            const stop = async () => {
+                try {
+                    if (!exit.done)
+                        await call('stop');
+                }
+                finally {
+                    await terminate(child, exit, 2000);
+                }
+            };
+            try {
+                const identifierPath = join(plan.snapshot.dir, 'machine-id');
+                const identifier = plan.snapshot.restoring ? await readFile(identifierPath, 'utf8') : undefined;
+                const boot = await call('boot', {
+                    kernel: plan.kernelPath, initrd: plan.initramfsPath, cmdline: plan.kernelCmdline,
+                    ...(options.consoleLogPath ? { consoleLog: options.consoleLogPath } : {}),
+                    disk: plan.overlay.path, memoryMb: plan.memoryMb, vcpus: plan.vcpus,
+                    vsockSocket: plan.vsock.socketPath, portSocket: plan.ports.socketPath,
+                    ...(plan.snapshot.restoring ? { restoreFrom: join(plan.snapshot.dir, 'state'), machineIdentifier: identifier } : {}),
+                    network: { ...plan.network, macAddress: plan.network.mac },
+                });
+                if (typeof boot.machineIdentifier !== 'string')
+                    throw new DeskError('Helper did not return a machine identifier.');
+                const machineIdentifier = boot.machineIdentifier;
+                if (plan.snapshot.restoring) {
+                    if (!hooks?.onRestored)
+                        throw new DeskError('Restore requires snapshot invalidation before resume.');
+                    await hooks.onRestored();
+                    await call('resume');
+                }
+                const connectAgent = (abandoned) => connectWithRetry({
+                    connect: options.connect ?? defaultConnect, now: Date.now, socketPath: plan.vsock.socketPath,
+                    port: options.guestAgentPort ?? GUEST_AGENT_VSOCK_PORT, timeoutMs: timeout, retryDelayMs: 100,
+                    attemptTimeoutMs: 5000, exited: exit, abandoned,
+                });
+                const stream = await connectAgent();
+                return createGuestMachine({
+                    deskId: plan.deskId, exit, stream, reconnect: connectAgent, reconnectWindowMs: timeout,
+                    now: Date.now, idFactory: randomUUID, requestTimeoutMs: options.requestTimeoutMs ?? 30_000,
+                    stop,
+                    connect: (port) => attemptHandshake(options.connect ?? defaultConnect, plan.ports.socketPath, port, 5000),
+                    ...(boot.saveRestore === true ? {
+                        park: async (dir) => {
+                            try {
+                                await call('save', { path: join(dir, 'state') });
+                                await writeFile(join(dir, 'machine-id'), machineIdentifier, { mode: 0o600 });
+                            }
+                            finally {
+                                await stop();
+                            }
+                        },
+                    } : {}),
+                });
+            }
+            catch (error) {
+                await terminate(child, exit, 2000);
+                throw new DeskError(`Virtualization desk ${plan.deskId} failed: ${errorMessage(error)}${log.tail() ? ` (${log.tail()})` : ''}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=virtualization.js.map

package/virtualization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualization.js","sourceRoot":"","sources":["../src/virtualization.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process'\nimport { randomUUID } from 'node:crypto'\nimport { mkdir, readFile, writeFile } from 'node:fs/promises'\nimport { dirname, isAbsolute, join } from 'node:path'\nimport { createInterface } from 'node:readline'\nimport type { Duplex } from 'node:stream'\nimport type { DeskBackend, DeskProcessLauncher } from './backend'\nimport { DeskError } from './plan'\nimport { GUEST_AGENT_VSOCK_PORT } from './protocol'\nimport {\n  attemptHandshake, connectWithRetry, createGuestMachine, defaultConnect, drainOutput,\n  errorMessage, runToCompletion, terminate, watchExit,\n} from './machine'\n\n/** A signed helper is supplied by the host; it is not downloaded or executed at install time. */\nexport interface VirtualizationBackendOptions {\n  helperPath: string\n  launcher?: DeskProcessLauncher\n  connect?: (socketPath: string) => Duplex\n  connectTimeoutMs?: number\n  /** Existing file for the guest serial console; omit to disable it. */\n  consoleLogPath?: string\n  requestTimeoutMs?: number\n  guestAgentPort?: number\n  platform?: NodeJS.Platform\n}\n\nexport function createVirtualizationBackend(options: VirtualizationBackendOptions): DeskBackend {\n  if (options.consoleLogPath && !isAbsolute(options.consoleLogPath)) throw new DeskError('consoleLogPath must be an absolute path.')\n  if (!isAbsolute(options.helperPath)) throw new DeskError('helperPath must be an absolute path.')\n  const launcher: DeskProcessLauncher = options.launcher ?? ((command, args, { identity }) => spawn(command, [...args], {\n    stdio: ['pipe', 'pipe', 'pipe'], uid: identity?.uid, gid: identity?.gid,\n  }))\n  const timeout = options.connectTimeoutMs ?? 30_000\n  return {\n    hypervisor: 'virtualization',\n    vmmPath: options.helperPath,\n    async boot(plan, hooks) {\n      if (plan.hypervisor !== 'virtualization') throw new DeskError('Virtualization backend requires a virtualization plan.')\n      if ((options.platform ?? process.platform) !== 'darwin') throw new DeskError('Virtualization requires macOS.')\n      if (plan.overlay.create) await runToCompletion(launcher(plan.overlay.create.command, plan.overlay.create.args, { identity: plan.launcherIdentity }), `overlay creation for desk ${plan.deskId}`)\n      await mkdir(dirname(plan.vsock.socketPath), { recursive: true, mode: 0o700 })\n      const child = launcher(options.helperPath, [], { identity: plan.launcherIdentity })\n      const exit = watchExit(child)\n      const log = drainOutput(child, 8192, ['stderr'])\n      if (!child.stdin || !child.stdout) {\n        await terminate(child, exit, 2000)\n        throw new DeskError('Virtualization helper requires piped stdin and stdout.')\n      }\n      const input = child.stdin\n      // A helper exit may close stdin while a write is in flight.\n      input.on('error', () => undefined)\n      const pending = new Map<string, { resolve: (value: Record<string, unknown>) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }>()\n      const lines = createInterface({ input: child.stdout })\n      lines.on('line', (line) => {\n        let message: Record<string, unknown>\n        try { message = JSON.parse(line) as Record<string, unknown> } catch { return }\n        if (!message || typeof message !== 'object' || typeof message.id !== 'string') return\n        const entry = pending.get(message.id)\n        if (!entry) return\n        pending.delete(message.id); clearTimeout(entry.timer)\n        if (message.ok === true && message.result && typeof message.result === 'object') entry.resolve(message.result as Record<string, unknown>)\n        else entry.reject(new DeskError(String(message.error ?? 'Helper request failed.')))\n      })\n      void exit.promise.then(() => {\n        for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new DeskError(`Virtualization helper exited: ${log.tail()}`)) }\n        pending.clear(); lines.close()\n      })\n      function call(op: string, fields: Record<string, unknown> = {}): Promise<Record<string, unknown>> {\n        if (exit.done) return Promise.reject(new DeskError('Virtualization helper exited.'))\n        const id = randomUUID()\n        return new Promise((resolve, reject) => {\n          const timer = setTimeout(() => { pending.delete(id); reject(new DeskError(`Virtualization helper ${op} timed out.`)) }, timeout)\n          pending.set(id, { resolve, reject, timer })\n          input.write(`${JSON.stringify({ ...fields, id, op })}\\n`, (error) => {\n            if (error) { const entry = pending.get(id); if (entry) { clearTimeout(entry.timer); pending.delete(id); reject(error) } }\n          })\n        })\n      }\n      const stop = async () => {\n        try { if (!exit.done) await call('stop') } finally { await terminate(child, exit, 2000) }\n      }\n      try {\n        const identifierPath = join(plan.snapshot.dir, 'machine-id')\n        const identifier = plan.snapshot.restoring ? await readFile(identifierPath, 'utf8') : undefined\n        const boot = await call('boot', {\n          kernel: plan.kernelPath, initrd: plan.initramfsPath, cmdline: plan.kernelCmdline,\n          ...(options.consoleLogPath ? { consoleLog: options.consoleLogPath } : {}),\n          disk: plan.overlay.path, memoryMb: plan.memoryMb, vcpus: plan.vcpus,\n          vsockSocket: plan.vsock.socketPath, portSocket: plan.ports.socketPath,\n          ...(plan.snapshot.restoring ? { restoreFrom: join(plan.snapshot.dir, 'state'), machineIdentifier: identifier } : {}),\n          network: { ...plan.network, macAddress: plan.network.mac },\n        })\n        if (typeof boot.machineIdentifier !== 'string') throw new DeskError('Helper did not return a machine identifier.')\n        const machineIdentifier = boot.machineIdentifier\n        if (plan.snapshot.restoring) {\n          if (!hooks?.onRestored) throw new DeskError('Restore requires snapshot invalidation before resume.')\n          await hooks.onRestored()\n          await call('resume')\n        }\n        const connectAgent = (abandoned?: () => boolean) => connectWithRetry({\n          connect: options.connect ?? defaultConnect, now: Date.now, socketPath: plan.vsock.socketPath,\n          port: options.guestAgentPort ?? GUEST_AGENT_VSOCK_PORT, timeoutMs: timeout, retryDelayMs: 100,\n          attemptTimeoutMs: 5000, exited: exit, abandoned,\n        })\n        const stream = await connectAgent()\n        return createGuestMachine({\n          deskId: plan.deskId, exit, stream, reconnect: connectAgent, reconnectWindowMs: timeout,\n          now: Date.now, idFactory: randomUUID, requestTimeoutMs: options.requestTimeoutMs ?? 30_000,\n          stop,\n          connect: (port) => attemptHandshake(options.connect ?? defaultConnect, plan.ports.socketPath, port, 5000),\n          ...(boot.saveRestore === true ? {\n            park: async (dir: string) => {\n              try {\n                await call('save', { path: join(dir, 'state') })\n                await writeFile(join(dir, 'machine-id'), machineIdentifier, { mode: 0o600 })\n              } finally { await stop() }\n            },\n          } : {}),\n        })\n      } catch (error) {\n        await terminate(child, exit, 2000)\n        throw new DeskError(`Virtualization desk ${plan.deskId} failed: ${errorMessage(error)}${log.tail() ? ` (${log.tail()})` : ''}`)\n      }\n    },\n  }\n}\n"]}

package/vz/Package.swift

@@ -0,0 +1,23 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+  name: "appkit-desk-vz",
+  platforms: [.macOS(.v14)],
+  products: [
+    .executable(name: "appkit-desk-vz", targets: ["appkit-desk-vz"]),
+  ],
+  targets: [
+    // The userspace network: Ethernet in, host sockets out, and the fence in
+    // between. No Virtualization.framework dependency, so it is unit-tested on
+    // its own against an in-memory guest.
+    .target(name: "DeskNet"),
+    .executableTarget(
+      name: "appkit-desk-vz",
+      dependencies: ["DeskNet"],
+      linkerSettings: [.linkedFramework("Virtualization")]
+    ),
+    .testTarget(name: "DeskNetTests", dependencies: ["DeskNet"]),
+  ],
+  swiftLanguageModes: [.v6]
+)

package/vz/Sources/DeskNet/Addresses.swift

@@ -0,0 +1,106 @@
+/// IPv4 and MAC addresses, and the CIDR blocks the fence is written in.
+public struct IPv4: Hashable, Comparable, Sendable, CustomStringConvertible {
+  public var value: UInt32
+
+  public init(_ value: UInt32) { self.value = value }
+
+  public init(_ a: UInt8, _ b: UInt8, _ c: UInt8, _ d: UInt8) {
+    value = UInt32(a) << 24 | UInt32(b) << 16 | UInt32(c) << 8 | UInt32(d)
+  }
+
+  /// Strict dotted-quad parsing: four decimal octets, nothing else.
+  public init?(_ text: String) {
+    let parts = text.split(separator: ".", omittingEmptySubsequences: false)
+    guard parts.count == 4 else { return nil }
+    var result: UInt32 = 0
+    for part in parts {
+      guard !part.isEmpty, part.count <= 3, part.allSatisfy({ $0.isASCII && $0.isNumber }),
+        let octet = UInt32(part), octet <= 255
+      else { return nil }
+      result = result << 8 | octet
+    }
+    value = result
+  }
+
+  init(bytes: [UInt8], at offset: Int) {
+    value = UInt32(bytes[offset]) << 24 | UInt32(bytes[offset + 1]) << 16
+      | UInt32(bytes[offset + 2]) << 8 | UInt32(bytes[offset + 3])
+  }
+
+  public var bytes: [UInt8] {
+    [UInt8(value >> 24 & 0xff), UInt8(value >> 16 & 0xff), UInt8(value >> 8 & 0xff), UInt8(value & 0xff)]
+  }
+
+  public var description: String { bytes.map(String.init).joined(separator: ".") }
+
+  public static let zero = IPv4(0)
+  public static let broadcast = IPv4(0xffff_ffff)
+
+  public static func < (lhs: IPv4, rhs: IPv4) -> Bool { lhs.value < rhs.value }
+}
+
+public struct CIDR: Hashable, Sendable, CustomStringConvertible {
+  public let base: IPv4
+  public let prefix: Int
+
+  public init(_ base: IPv4, _ prefix: Int) {
+    precondition((0...32).contains(prefix), "prefix out of range")
+    self.prefix = prefix
+    self.base = IPv4(base.value & CIDR.mask(prefix))
+  }
+
+  public init?(_ text: String) {
+    let parts = text.split(separator: "/")
+    guard parts.count == 2, let base = IPv4(String(parts[0])), let prefix = Int(parts[1]),
+      (0...32).contains(prefix)
+    else { return nil }
+    self.init(base, prefix)
+  }
+
+  public var mask: UInt32 { CIDR.mask(prefix) }
+
+  public func contains(_ address: IPv4) -> Bool {
+    address.value & mask == base.value
+  }
+
+  public var description: String { "\(base)/\(prefix)" }
+
+  static func mask(_ prefix: Int) -> UInt32 {
+    prefix == 0 ? 0 : UInt32.max << UInt32(32 - prefix)
+  }
+}
+
+public struct MAC: Hashable, Sendable, CustomStringConvertible {
+  public let bytes: [UInt8]
+
+  public init(_ bytes: [UInt8]) {
+    precondition(bytes.count == 6, "a MAC address is six bytes")
+    self.bytes = bytes
+  }
+
+  public init?(_ text: String) {
+    let parts = text.split(separator: ":")
+    guard parts.count == 6 else { return nil }
+    var bytes: [UInt8] = []
+    for part in parts {
+      guard part.count == 2, let byte = UInt8(part, radix: 16) else { return nil }
+      bytes.append(byte)
+    }
+    self.bytes = bytes
+  }
+
+  public var description: String {
+    bytes.map { byte in
+      let hex = String(byte, radix: 16)
+      return hex.count == 1 ? "0" + hex : hex
+    }.joined(separator: ":")
+  }
+
+  public static let broadcast = MAC([0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
+  /// The gateway's address on the virtual link. Locally administered and
+  /// constant, because a restored guest keeps it in its ARP cache.
+  public static let gateway = MAC([0x5a, 0x94, 0xef, 0xe4, 0x0c, 0xdd])
+
+  public var isBroadcast: Bool { self == .broadcast }
+  public var isMulticast: Bool { bytes[0] & 1 == 1 }
+}

package/vz/Sources/DeskNet/DHCP.swift

@@ -0,0 +1,111 @@
+/// The smallest DHCP server that hands one guest its one address.
+///
+/// The link has exactly one client, so there is no pool and no lease table:
+/// every DISCOVER is offered the configured guest address and every REQUEST
+/// for it is acknowledged. A guest configured statically never asks, and that
+/// works too — the server is a convenience, not a gate.
+public struct DHCPServer: Sendable {
+  public let guest: IPv4
+  public let gateway: IPv4
+  public let prefixLength: Int
+  public let dns: [IPv4]
+  public let leaseSeconds: UInt32
+
+  public init(guest: IPv4, gateway: IPv4, prefixLength: Int, dns: [IPv4], leaseSeconds: UInt32 = 86_400) {
+    self.guest = guest
+    self.gateway = gateway
+    self.prefixLength = prefixLength
+    self.dns = dns
+    self.leaseSeconds = leaseSeconds
+  }
+
+  static let magicCookie: [UInt8] = [99, 130, 83, 99]
+
+  enum MessageType: UInt8 {
+    case discover = 1, offer, request, decline, ack, nak, release, inform
+  }
+
+  public struct Reply: Sendable {
+    /// The BOOTP payload to send from the server port to the client port.
+    public let payload: [UInt8]
+    /// Where the reply goes on the link: the client's hardware address.
+    public let clientMAC: MAC
+    /// True when the guest was just given (or confirmed in) its address.
+    public let assigned: Bool
+  }
+
+  /// Answer one client message, or nil when it needs no answer.
+  public func respond(to bytes: [UInt8]) -> Reply? {
+    guard bytes.count >= 240, bytes[0] == 1, bytes[1] == 1, bytes[2] == 6,
+      Array(bytes[236..<240]) == Self.magicCookie
+    else { return nil }
+    let options = Self.options(bytes)
+    guard let typeByte = options[53]?.first, let type = MessageType(rawValue: typeByte) else {
+      return nil
+    }
+    let clientMAC = MAC(Array(bytes[28..<34]))
+    let ciaddr = IPv4(bytes: bytes, at: 12)
+    switch type {
+    case .discover:
+      return Reply(payload: reply(to: bytes, type: .offer, yiaddr: guest), clientMAC: clientMAC, assigned: false)
+    case .request:
+      let requested = options[50].flatMap { $0.count == 4 ? IPv4(bytes: $0, at: 0) : nil } ?? ciaddr
+      if requested == guest || requested == .zero {
+        return Reply(payload: reply(to: bytes, type: .ack, yiaddr: guest), clientMAC: clientMAC, assigned: true)
+      }
+      return Reply(payload: reply(to: bytes, type: .nak, yiaddr: .zero), clientMAC: clientMAC, assigned: false)
+    case .inform:
+      return Reply(payload: reply(to: bytes, type: .ack, yiaddr: .zero, inform: true), clientMAC: clientMAC, assigned: false)
+    case .offer, .decline, .ack, .nak, .release:
+      return nil
+    }
+  }
+
+  static func options(_ bytes: [UInt8]) -> [UInt8: [UInt8]] {
+    var result: [UInt8: [UInt8]] = [:]
+    var index = 240
+    while index < bytes.count {
+      let code = bytes[index]
+      if code == 255 { break }
+      if code == 0 {
+        index += 1
+        continue
+      }
+      guard index + 1 < bytes.count else { break }
+      let length = Int(bytes[index + 1])
+      guard index + 2 + length <= bytes.count else { break }
+      result[code] = Array(bytes[(index + 2)..<(index + 2 + length)])
+      index += 2 + length
+    }
+    return result
+  }
+
+  private func reply(to request: [UInt8], type: MessageType, yiaddr: IPv4, inform: Bool = false) -> [UInt8] {
+    var bytes = [UInt8](repeating: 0, count: 240)
+    bytes[0] = 2
+    bytes[1] = 1
+    bytes[2] = 6
+    bytes[4..<8] = request[4..<8]  // xid
+    bytes[10..<12] = request[10..<12]  // flags
+    bytes[12..<16] = request[12..<16]  // ciaddr
+    put32(&bytes, 16, yiaddr.value)
+    bytes[24..<28] = request[24..<28]  // giaddr
+    bytes[28..<44] = request[28..<44]  // chaddr
+    bytes[236..<240] = Self.magicCookie[0..<4]
+    var options: [UInt8] = [53, 1, type.rawValue, 54, 4] + gateway.bytes
+    if type != .nak {
+      options += [1, 4] + IPv4(CIDR.mask(prefixLength)).bytes
+      options += [3, 4] + gateway.bytes
+      if !dns.isEmpty {
+        options += [6, UInt8(dns.count * 4)] + dns.flatMap(\.bytes)
+      }
+      if !inform {
+        var lease = [UInt8](repeating: 0, count: 4)
+        put32(&lease, 0, leaseSeconds)
+        options += [51, 4] + lease
+      }
+    }
+    options.append(255)
+    return bytes + options
+  }
+}

package/vz/Sources/DeskNet/Fence.swift

@@ -0,0 +1,57 @@
+/// Where a guest may send traffic.
+///
+/// The guest reaches the public internet and nothing else by default: not the
+/// Mac's LAN, not link-local services (cloud metadata lives at 169.254.169.254),
+/// not carrier-grade NAT space (where Tailscale and similar overlays put their
+/// peers), and not the Mac itself on any of its addresses. `allowLan` lifts
+/// that, for a computer the owner has explicitly let onto their network.
+///
+/// Some destinations are never meaningful through a NAT whatever the setting:
+/// "this network", loopback (the guest's own loopback never leaves the guest,
+/// so a packet for 127/8 arriving here is spoofed or broken), multicast, and
+/// the reserved, documentation and broadcast space.
+public struct EgressFence: Sendable {
+  public var allowLan: Bool
+
+  public init(allowLan: Bool) { self.allowLan = allowLan }
+
+  public static let alwaysDenied: [CIDR] = [
+    CIDR(IPv4(0, 0, 0, 0), 8),
+    CIDR(IPv4(127, 0, 0, 0), 8),
+    CIDR(IPv4(192, 0, 2, 0), 24),
+    CIDR(IPv4(198, 51, 100, 0), 24),
+    CIDR(IPv4(203, 0, 113, 0), 24),
+    CIDR(IPv4(224, 0, 0, 0), 4),
+    CIDR(IPv4(240, 0, 0, 0), 4),
+  ]
+
+  /// Private, link-local, shared and special-purpose space a guest is fenced
+  /// out of unless the LAN is allowed.
+  public static let localRanges: [CIDR] = [
+    CIDR(IPv4(10, 0, 0, 0), 8),
+    CIDR(IPv4(172, 16, 0, 0), 12),
+    CIDR(IPv4(192, 168, 0, 0), 16),
+    CIDR(IPv4(169, 254, 0, 0), 16),
+    CIDR(IPv4(100, 64, 0, 0), 10),
+    CIDR(IPv4(192, 0, 0, 0), 24),
+    CIDR(IPv4(198, 18, 0, 0), 15),
+  ]
+
+  public enum Verdict: Equatable, Sendable {
+    case allowed
+    /// Never routable through the NAT.
+    case invalid
+    /// Fenced off: local network space or the Mac itself.
+    case fenced
+  }
+
+  /// Judge a destination. `hostAddresses` are the Mac's own IPv4 addresses on
+  /// every interface, which are fenced even when public.
+  public func verdict(for destination: IPv4, hostAddresses: Set<IPv4>) -> Verdict {
+    if Self.alwaysDenied.contains(where: { $0.contains(destination) }) { return .invalid }
+    if allowLan { return .allowed }
+    if Self.localRanges.contains(where: { $0.contains(destination) }) { return .fenced }
+    if hostAddresses.contains(destination) { return .fenced }
+    return .allowed
+  }
+}