@braedonsaunders/appkit-desk 0.6.0 → 0.8.0

package/network.js

@@ -0,0 +1,173 @@
+import { execFile } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const defaultRunner = {
+    async run(command, args) {
+        try {
+            return (await execFileAsync(command, [...args], { timeout: 15_000 })).stdout;
+        }
+        catch (error) {
+            const failure = error;
+            throw new Error(`${command} ${args.join(' ')}: ${(failure.stderr || failure.message || String(error)).trim()}`);
+        }
+    },
+};
+async function forwarding() {
+    const path = '/proc/sys/net/ipv4/ip_forward';
+    if ((await readFile(path, 'utf8').catch(() => '')).trim() !== '1')
+        await writeFile(path, '1');
+}
+function port(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 65535)
+        throw new Error('Invalid TCP port');
+}
+function address(value) {
+    if (isIP(value) !== 4)
+        throw new Error(`Invalid IPv4 address: ${value}`);
+}
+/** Deterministic TAP and locally administered MAC for an unsigned desk index. */
+export function deskNetworkIdentity(index) {
+    if (!Number.isInteger(index) || index < 2 || index > 999999999)
+        throw new Error('Invalid desk network index');
+    const octets = [6, 0, (index >>> 24) & 255, (index >>> 16) & 255, (index >>> 8) & 255, index & 255];
+    return { tap: `dsk${index}`, macAddress: octets.map((octet) => octet.toString(16).padStart(2, '0')).join(':') };
+}
+/** Point-to-point TAP with either open or transparent-proxy egress. */
+export function createDeskNetwork(options) {
+    address(options.gateway);
+    address(options.dns);
+    const egress = options.egress;
+    if (egress.mode === 'proxied') {
+        port(egress.httpProxyPort);
+        port(egress.httpsProxyPort);
+    }
+    else if (egress.mode !== 'open')
+        throw new Error('Invalid egress mode');
+    const chainPrefix = options.chainPrefix ?? 'desk';
+    if (!/^[A-Za-z0-9_-]+$/.test(chainPrefix))
+        throw new Error('Invalid iptables chain prefix');
+    const hostPorts = [...(options.allowHostPorts ?? [])];
+    hostPorts.forEach(port);
+    const prefix = options.prefixLength ?? 24;
+    if (!Number.isInteger(prefix) || prefix < 1 || prefix > 32)
+        throw new Error('Invalid guest prefix length');
+    const runner = options.runner ?? defaultRunner;
+    const enableForwarding = options.enableForwarding ?? forwarding;
+    const work = new Map();
+    const run = (command, args) => runner.run(command, args);
+    const succeeds = async (command, args) => { try {
+        await run(command, args);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    function validate(value) {
+        if (!/^dsk[0-9]{1,9}$/.test(value.tap))
+            throw new Error('Invalid TAP name');
+        if (`${chainPrefix}-post-${value.tap}`.length > 28)
+            throw new Error('iptables chain name exceeds 28 characters');
+        address(value.guest);
+        if (value.guest === options.gateway)
+            throw new Error('Guest and gateway addresses must differ');
+    }
+    function chains({ tap, guest }) {
+        const { gateway, dns } = options;
+        const proxyRules = egress.mode === 'proxied' ? [
+            ['-p', 'tcp', '--dport', '80', '-j', 'DNAT', '--to-destination', `${gateway}:${egress.httpProxyPort}`],
+            ['-p', 'tcp', '--dport', '443', '-j', 'DNAT', '--to-destination', `${gateway}:${egress.httpsProxyPort}`],
+            ...['udp', 'tcp'].map((p) => ['-p', p, '--dport', '53', '-j', 'DNAT', '--to-destination', `${dns}:53`]),
+        ] : [];
+        const proxyPorts = egress.mode === 'proxied'
+            ? [egress.httpProxyPort, egress.httpsProxyPort].map((p) => ['-p', 'tcp', '-d', gateway, '--dport', String(p), '-j', 'ACCEPT'])
+            : [];
+        const extraPorts = hostPorts.flatMap((p) => ['tcp', 'udp'].map((protocol) => ['-p', protocol, '-d', gateway, '--dport', String(p), '-j', 'ACCEPT']));
+        const forwardRules = egress.mode === 'proxied' ? [
+            ['-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],
+            ...['udp', 'tcp'].map((p) => ['-i', tap, '-p', p, '-d', dns, '--dport', '53', '-j', 'ACCEPT']),
+            ['-j', 'DROP'],
+        ] : [
+            ['-o', tap, '-d', `${guest}/32`, '-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],
+            ['-i', tap, '-s', `${guest}/32`, '-j', 'ACCEPT'],
+            ['-j', 'DROP'],
+        ];
+        return [
+            { table: 'nat', parent: 'PREROUTING', chain: `${chainPrefix}-pre-${tap}`, jumps: [['-i', tap]], rules: proxyRules },
+            { table: 'nat', parent: 'POSTROUTING', chain: `${chainPrefix}-post-${tap}`, jumps: [['-s', `${guest}/32`]], rules: [['-j', 'MASQUERADE']] },
+            { table: 'filter', parent: 'INPUT', chain: `${chainPrefix}-in-${tap}`, jumps: [['-i', tap]], rules: [
+                    ['-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],
+                    ...proxyPorts, ...extraPorts, ['-j', 'DROP'],
+                ] },
+            { table: 'filter', parent: 'FORWARD', chain: `${chainPrefix}-fwd-${tap}`, jumps: [['-i', tap], ['-o', tap]], rules: forwardRules },
+            ...(egress.mode === 'open' ? [
+                { command: 'ip6tables', table: 'filter', parent: 'INPUT', chain: `${chainPrefix}-6in-${tap}`, jumps: [['-i', tap]], rules: [['-j', 'DROP']] },
+                { command: 'ip6tables', table: 'filter', parent: 'FORWARD', chain: `${chainPrefix}-6fwd-${tap}`, jumps: [['-i', tap], ['-o', tap]], rules: [['-j', 'DROP']] },
+            ] : []),
+        ];
+    }
+    function serialize(tap, fn) {
+        const next = (work.get(tap) ?? Promise.resolve()).then(fn);
+        const settled = next.then(() => undefined, () => undefined);
+        work.set(tap, settled);
+        void settled.then(() => { if (work.get(tap) === settled)
+            work.delete(tap); });
+        return next;
+    }
+    return {
+        ensure(value) {
+            validate(value);
+            return serialize(value.tap, async () => {
+                const { tap, guest } = value;
+                if (!(await succeeds('ip', ['link', 'show', 'dev', tap])))
+                    await run('ip', ['tuntap', 'add', 'dev', tap, 'mode', 'tap']);
+                await run('ip', ['addr', 'replace', `${options.gateway}/32`, 'dev', tap]);
+                await run('ip', ['link', 'set', 'dev', tap, 'up']);
+                await run('ip', ['route', 'replace', `${guest}/32`, 'dev', tap]);
+                await enableForwarding();
+                for (const { table, parent, chain, jumps, rules, command = 'iptables' } of chains(value)) {
+                    await succeeds(command, ['-t', table, '-N', chain]);
+                    await run(command, ['-t', table, '-F', chain]);
+                    for (const rule of rules)
+                        await run(command, ['-t', table, '-A', chain, ...rule]);
+                    for (const jump of jumps) {
+                        const target = [...jump, '-j', chain];
+                        if (!(await succeeds(command, ['-t', table, '-C', parent, ...target])))
+                            await run(command, ['-t', table, '-I', parent, '1', ...target]);
+                    }
+                }
+            });
+        },
+        teardown(value) {
+            validate(value);
+            return serialize(value.tap, async () => {
+                for (const { table, parent, chain, jumps, command = 'iptables' } of chains(value)) {
+                    for (const jump of jumps)
+                        while (await succeeds(command, ['-t', table, '-C', parent, ...jump, '-j', chain])) {
+                            if (!(await succeeds(command, ['-t', table, '-D', parent, ...jump, '-j', chain])))
+                                break;
+                        }
+                    await succeeds(command, ['-t', table, '-F', chain]);
+                    await succeeds(command, ['-t', table, '-X', chain]);
+                }
+                await succeeds('ip', ['link', 'del', 'dev', value.tap]);
+            });
+        },
+        async configureGuest(desk, value) {
+            validate(value);
+            const script = ['set -e', 'dev=$(ls /sys/class/net | grep -E "^(en|eth)" | head -n 1)', 'test -n "$dev"', `ip addr replace ${value.guest}/${prefix} dev "$dev"`, 'ip link set dev "$dev" up', `ip route replace default via ${options.gateway} dev "$dev"`, 'rm -f /etc/resolv.conf', `printf 'nameserver %s\\n' ${options.dns} > /etc/resolv.conf`].join('\n');
+            const result = await desk.exec({ command: '/bin/sh', args: ['-c', script], timeoutMs: 20_000 });
+            if (result.exitCode !== 0)
+                throw new Error(`The guest's network could not be configured: ${result.stderr.trim() || 'no reason given'}`);
+        },
+    };
+}
+export async function syncDeskGuestClock(desk, now = Date.now()) {
+    if (!Number.isFinite(now) || now < 0)
+        throw new Error('Invalid clock time');
+    const result = await desk.exec({ command: '/bin/sh', args: ['-c', `date -u -s @${(now / 1000).toFixed(3)} > /dev/null`], timeoutMs: 5_000 });
+    if (result.exitCode !== 0)
+        throw new Error(`The guest's clock could not be set: ${result.stderr.trim() || 'no reason given'}`);
+}
+//# sourceMappingURL=network.js.map

package/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../src/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAiBrC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;AACzC,MAAM,aAAa,GAA6B;IAC9C,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI;QACrB,IAAI,CAAC;YAAC,OAAO,CAAC,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;QAAC,CAAC;QACpF,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,KAA8C,CAAA;YAC9D,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACjH,CAAC;IACH,CAAC;CACF,CAAA;AACD,KAAK,UAAU,UAAU;IACvB,MAAM,IAAI,GAAG,+BAA+B,CAAA;IAC5C,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG;QAAE,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAC/F,CAAC;AACD,SAAS,IAAI,CAAC,KAAa;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAA;AACjG,CAAC;AACD,SAAS,OAAO,CAAC,KAAa;IAC5B,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,EAAE,CAAC,CAAA;AAC1E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAA;IAC7G,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,GAAG,GAAG,CAAC,CAAA;IACnG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;AACjH,CAAC;AAID,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAC7B,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;IAAC,CAAC;SACrF,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAA;IACvE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAA;IACjD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAC3F,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,CAAA;IACrD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAA;IACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;IAC1G,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAA;IAC9C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,UAAU,CAAA;IAC/D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAA;IAC7C,MAAM,GAAG,GAAG,CAAC,OAAe,EAAE,IAAuB,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACnF,MAAM,QAAQ,GAAG,KAAK,EAAE,OAAe,EAAE,IAAuB,EAAE,EAAE,GAAG,IAAI,CAAC;QAAC,MAAM,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAAC,OAAO,IAAI,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAA;IAAC,CAAC,CAAC,CAAC,CAAA;IAC7I,SAAS,QAAQ,CAAC,KAAyB;QACzC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAA;QAC3E,IAAI,GAAG,WAAW,SAAS,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,GAAG,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;QAChH,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpB,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IACjG,CAAC;IACD,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,EAAsB;QAChD,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAA;QAChC,MAAM,UAAU,GAAW,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC;YACrD,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACtG,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YACxG,GAAI,CAAC,KAAK,EAAE,KAAK,CAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;SACnH,CAAC,CAAC,CAAC,EAAE,CAAA;QACN,MAAM,UAAU,GAAW,MAAM,CAAC,IAAI,KAAK,SAAS;YAClD,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC9H,CAAC,CAAC,EAAE,CAAA;QACN,MAAM,UAAU,GAAW,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAC,KAAK,EAAE,KAAK,CAAW,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAC7F,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;QACzE,MAAM,YAAY,GAAW,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC;YACvD,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,CAAC;YACvE,GAAI,CAAC,KAAK,EAAE,KAAK,CAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YACzG,CAAC,IAAI,EAAE,MAAM,CAAC;SACf,CAAC,CAAC,CAAC;YACF,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,CAAC;YACvG,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC;YAChD,CAAC,IAAI,EAAE,MAAM,CAAC;SACf,CAAA;QACD,OAAO;YACL,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,WAAW,QAAQ,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE;YACnH,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,WAAW,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,KAAK,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE;YAC3I,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,WAAW,OAAO,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE;oBAClG,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,CAAC;oBACvE,GAAG,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC;iBAC7C,EAAE;YACH,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,WAAW,QAAQ,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE;YAClI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC;gBAC3B,EAAE,OAAO,EAAE,WAAoB,EAAE,KAAK,EAAE,QAAiB,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,WAAW,QAAQ,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE;gBAC/J,EAAE,OAAO,EAAE,WAAoB,EAAE,KAAK,EAAE,QAAiB,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,WAAW,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE;aAChL,CAAC,CAAC,CAAC,EAAE,CAAC;SACR,CAAA;IACH,CAAC;IAED,SAAS,SAAS,CAAC,GAAW,EAAE,EAAuB;QACrD,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC3D,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QACtB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA,CAAC,CAAC,CAAC,CAAA;QAC5E,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO;QACL,MAAM,CAAC,KAAyB;YAC9B,QAAQ,CAAC,KAAK,CAAC,CAAA;YACf,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;gBACrC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;gBAC5B,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;oBAAE,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;gBACxH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;gBACzE,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAA;gBAClD,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;gBAChE,MAAM,gBAAgB,EAAE,CAAA;gBACxB,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzF,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;oBACnD,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;oBAC9C,KAAK,MAAM,IAAI,IAAI,KAAK;wBAAE,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;oBACjF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;wBACzB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;wBACrC,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;4BAAE,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,CAAC,CAAA;oBACzI,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QACD,QAAQ,CAAC,KAAyB;YAChC,QAAQ,CAAC,KAAK,CAAC,CAAA;YACf,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;gBACrC,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;oBAClF,KAAK,MAAM,IAAI,IAAI,KAAK;wBAAE,OAAO,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;4BAC5G,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;gCAAE,MAAK;wBAC1F,CAAC;oBACD,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;oBAAC,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;gBAC1G,CAAC;gBACD,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;YACzD,CAAC,CAAC,CAAA;QACJ,CAAC;QACD,KAAK,CAAC,cAAc,CAAC,IAA8B,EAAE,KAAyB;YAC5E,QAAQ,CAAC,KAAK,CAAC,CAAA;YACf,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,4DAA4D,EAAE,gBAAgB,EAAE,mBAAmB,KAAK,CAAC,KAAK,IAAI,MAAM,aAAa,EAAE,2BAA2B,EAAE,gCAAgC,OAAO,CAAC,OAAO,aAAa,EAAE,wBAAwB,EAAE,6BAA6B,OAAO,CAAC,GAAG,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC/V,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAA;YAC/F,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,iBAAiB,EAAE,CAAC,CAAA;QACzI,CAAC;KACF,CAAA;AACH,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAA8B,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACvF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAA;IAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5I,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,iBAAiB,EAAE,CAAC,CAAA;AAChI,CAAC","sourcesContent":["import { execFile } from 'node:child_process'\nimport { readFile, writeFile } from 'node:fs/promises'\nimport { isIP } from 'node:net'\nimport { promisify } from 'node:util'\nimport type { DeskHandle } from './host'\n\nexport interface DeskNetworkCommandRunner {\n  run(command: string, args: readonly string[]): Promise<string>\n}\nexport interface DeskNetworkOptions {\n  gateway: string\n  dns: string\n  egress: { mode: 'proxied'; httpProxyPort: number; httpsProxyPort: number } | { mode: 'open' }\n  chainPrefix?: string\n  allowHostPorts?: readonly number[]\n  prefixLength?: number\n  runner?: DeskNetworkCommandRunner\n  enableForwarding?: () => Promise<void>\n}\nexport interface DeskNetworkAddress { tap: string; guest: string }\nconst execFileAsync = promisify(execFile)\nconst defaultRunner: DeskNetworkCommandRunner = {\n  async run(command, args) {\n    try { return (await execFileAsync(command, [...args], { timeout: 15_000 })).stdout }\n    catch (error) {\n      const failure = error as { stderr?: string; message?: string }\n      throw new Error(`${command} ${args.join(' ')}: ${(failure.stderr || failure.message || String(error)).trim()}`)\n    }\n  },\n}\nasync function forwarding(): Promise<void> {\n  const path = '/proc/sys/net/ipv4/ip_forward'\n  if ((await readFile(path, 'utf8').catch(() => '')).trim() !== '1') await writeFile(path, '1')\n}\nfunction port(value: number): void {\n  if (!Number.isInteger(value) || value < 1 || value > 65535) throw new Error('Invalid TCP port')\n}\nfunction address(value: string): void {\n  if (isIP(value) !== 4) throw new Error(`Invalid IPv4 address: ${value}`)\n}\n\n/** Deterministic TAP and locally administered MAC for an unsigned desk index. */\nexport function deskNetworkIdentity(index: number): { tap: string; macAddress: string } {\n  if (!Number.isInteger(index) || index < 2 || index > 999999999) throw new Error('Invalid desk network index')\n  const octets = [6, 0, (index >>> 24) & 255, (index >>> 16) & 255, (index >>> 8) & 255, index & 255]\n  return { tap: `dsk${index}`, macAddress: octets.map((octet) => octet.toString(16).padStart(2, '0')).join(':') }\n}\n\ntype Rule = readonly string[]\ninterface Chain { table: 'nat' | 'filter'; parent: string; chain: string; jumps: Rule[]; rules: Rule[]; command?: 'ip6tables' }\n/** Point-to-point TAP with either open or transparent-proxy egress. */\nexport function createDeskNetwork(options: DeskNetworkOptions) {\n  address(options.gateway); address(options.dns)\n  const egress = options.egress\n  if (egress.mode === 'proxied') { port(egress.httpProxyPort); port(egress.httpsProxyPort) }\n  else if (egress.mode !== 'open') throw new Error('Invalid egress mode')\n  const chainPrefix = options.chainPrefix ?? 'desk'\n  if (!/^[A-Za-z0-9_-]+$/.test(chainPrefix)) throw new Error('Invalid iptables chain prefix')\n  const hostPorts = [...(options.allowHostPorts ?? [])]\n  hostPorts.forEach(port)\n  const prefix = options.prefixLength ?? 24\n  if (!Number.isInteger(prefix) || prefix < 1 || prefix > 32) throw new Error('Invalid guest prefix length')\n  const runner = options.runner ?? defaultRunner\n  const enableForwarding = options.enableForwarding ?? forwarding\n  const work = new Map<string, Promise<void>>()\n  const run = (command: string, args: readonly string[]) => runner.run(command, args)\n  const succeeds = async (command: string, args: readonly string[]) => { try { await run(command, args); return true } catch { return false } }\n  function validate(value: DeskNetworkAddress) {\n    if (!/^dsk[0-9]{1,9}$/.test(value.tap)) throw new Error('Invalid TAP name')\n    if (`${chainPrefix}-post-${value.tap}`.length > 28) throw new Error('iptables chain name exceeds 28 characters')\n    address(value.guest)\n    if (value.guest === options.gateway) throw new Error('Guest and gateway addresses must differ')\n  }\n  function chains({ tap, guest }: DeskNetworkAddress): Chain[] {\n    const { gateway, dns } = options\n    const proxyRules: Rule[] = egress.mode === 'proxied' ? [\n      ['-p', 'tcp', '--dport', '80', '-j', 'DNAT', '--to-destination', `${gateway}:${egress.httpProxyPort}`],\n      ['-p', 'tcp', '--dport', '443', '-j', 'DNAT', '--to-destination', `${gateway}:${egress.httpsProxyPort}`],\n      ...(['udp', 'tcp'] as const).map((p) => ['-p', p, '--dport', '53', '-j', 'DNAT', '--to-destination', `${dns}:53`]),\n    ] : []\n    const proxyPorts: Rule[] = egress.mode === 'proxied'\n      ? [egress.httpProxyPort, egress.httpsProxyPort].map((p) => ['-p', 'tcp', '-d', gateway, '--dport', String(p), '-j', 'ACCEPT'])\n      : []\n    const extraPorts: Rule[] = hostPorts.flatMap((p) => (['tcp', 'udp'] as const).map((protocol) =>\n      ['-p', protocol, '-d', gateway, '--dport', String(p), '-j', 'ACCEPT']))\n    const forwardRules: Rule[] = egress.mode === 'proxied' ? [\n      ['-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],\n      ...(['udp', 'tcp'] as const).map((p) => ['-i', tap, '-p', p, '-d', dns, '--dport', '53', '-j', 'ACCEPT']),\n      ['-j', 'DROP'],\n    ] : [\n      ['-o', tap, '-d', `${guest}/32`, '-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],\n      ['-i', tap, '-s', `${guest}/32`, '-j', 'ACCEPT'],\n      ['-j', 'DROP'],\n    ]\n    return [\n      { table: 'nat', parent: 'PREROUTING', chain: `${chainPrefix}-pre-${tap}`, jumps: [['-i', tap]], rules: proxyRules },\n      { table: 'nat', parent: 'POSTROUTING', chain: `${chainPrefix}-post-${tap}`, jumps: [['-s', `${guest}/32`]], rules: [['-j', 'MASQUERADE']] },\n      { table: 'filter', parent: 'INPUT', chain: `${chainPrefix}-in-${tap}`, jumps: [['-i', tap]], rules: [\n        ['-m', 'conntrack', '--ctstate', 'ESTABLISHED,RELATED', '-j', 'ACCEPT'],\n        ...proxyPorts, ...extraPorts, ['-j', 'DROP'],\n      ] },\n      { table: 'filter', parent: 'FORWARD', chain: `${chainPrefix}-fwd-${tap}`, jumps: [['-i', tap], ['-o', tap]], rules: forwardRules },\n      ...(egress.mode === 'open' ? [\n        { command: 'ip6tables' as const, table: 'filter' as const, parent: 'INPUT', chain: `${chainPrefix}-6in-${tap}`, jumps: [['-i', tap]], rules: [['-j', 'DROP']] },\n        { command: 'ip6tables' as const, table: 'filter' as const, parent: 'FORWARD', chain: `${chainPrefix}-6fwd-${tap}`, jumps: [['-i', tap], ['-o', tap]], rules: [['-j', 'DROP']] },\n      ] : []),\n    ]\n  }\n\n  function serialize(tap: string, fn: () => Promise<void>): Promise<void> {\n    const next = (work.get(tap) ?? Promise.resolve()).then(fn)\n    const settled = next.then(() => undefined, () => undefined)\n    work.set(tap, settled)\n    void settled.then(() => { if (work.get(tap) === settled) work.delete(tap) })\n    return next\n  }\n  return {\n    ensure(value: DeskNetworkAddress): Promise<void> {\n      validate(value)\n      return serialize(value.tap, async () => {\n        const { tap, guest } = value\n        if (!(await succeeds('ip', ['link', 'show', 'dev', tap]))) await run('ip', ['tuntap', 'add', 'dev', tap, 'mode', 'tap'])\n        await run('ip', ['addr', 'replace', `${options.gateway}/32`, 'dev', tap])\n        await run('ip', ['link', 'set', 'dev', tap, 'up'])\n        await run('ip', ['route', 'replace', `${guest}/32`, 'dev', tap])\n        await enableForwarding()\n        for (const { table, parent, chain, jumps, rules, command = 'iptables' } of chains(value)) {\n          await succeeds(command, ['-t', table, '-N', chain])\n          await run(command, ['-t', table, '-F', chain])\n          for (const rule of rules) await run(command, ['-t', table, '-A', chain, ...rule])\n          for (const jump of jumps) {\n            const target = [...jump, '-j', chain]\n            if (!(await succeeds(command, ['-t', table, '-C', parent, ...target]))) await run(command, ['-t', table, '-I', parent, '1', ...target])\n          }\n        }\n      })\n    },\n    teardown(value: DeskNetworkAddress): Promise<void> {\n      validate(value)\n      return serialize(value.tap, async () => {\n        for (const { table, parent, chain, jumps, command = 'iptables' } of chains(value)) {\n          for (const jump of jumps) while (await succeeds(command, ['-t', table, '-C', parent, ...jump, '-j', chain])) {\n            if (!(await succeeds(command, ['-t', table, '-D', parent, ...jump, '-j', chain]))) break\n          }\n          await succeeds(command, ['-t', table, '-F', chain]); await succeeds(command, ['-t', table, '-X', chain])\n        }\n        await succeeds('ip', ['link', 'del', 'dev', value.tap])\n      })\n    },\n    async configureGuest(desk: Pick<DeskHandle, 'exec'>, value: DeskNetworkAddress): Promise<void> {\n      validate(value)\n      const script = ['set -e', 'dev=$(ls /sys/class/net | grep -E \"^(en|eth)\" | head -n 1)', 'test -n \"$dev\"', `ip addr replace ${value.guest}/${prefix} dev \"$dev\"`, 'ip link set dev \"$dev\" up', `ip route replace default via ${options.gateway} dev \"$dev\"`, 'rm -f /etc/resolv.conf', `printf 'nameserver %s\\\\n' ${options.dns} > /etc/resolv.conf`].join('\\n')\n      const result = await desk.exec({ command: '/bin/sh', args: ['-c', script], timeoutMs: 20_000 })\n      if (result.exitCode !== 0) throw new Error(`The guest's network could not be configured: ${result.stderr.trim() || 'no reason given'}`)\n    },\n  }\n}\nexport async function syncDeskGuestClock(desk: Pick<DeskHandle, 'exec'>, now = Date.now()): Promise<void> {\n  if (!Number.isFinite(now) || now < 0) throw new Error('Invalid clock time')\n  const result = await desk.exec({ command: '/bin/sh', args: ['-c', `date -u -s @${(now / 1000).toFixed(3)} > /dev/null`], timeoutMs: 5_000 })\n  if (result.exitCode !== 0) throw new Error(`The guest's clock could not be set: ${result.stderr.trim() || 'no reason given'}`)\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@braedonsaunders/appkit-desk",
-  "version": "0.6.0",
-  "description": "Per-agent Debian microVMs under Cloud Hypervisor — headless machines with an on-demand screen, a framed vsock guest-agent protocol, leases with idle suspend and a bounded queue, and load-bearing handover masking behind consumer-supplied policy and recording ports.",
+  "version": "0.8.0",
+  "description": "Per-agent Debian microVMs on Linux and macOS, with a framed guest-agent protocol, leases, snapshots, and governed networking.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "exports": {

package/plan.d.ts

@@ -5,6 +5,17 @@ export declare const DEFAULT_RUNTIME_DIR = "/run/appkit-desk";
 export declare const DEFAULT_MEMORY_MB = 384;
 export declare const DEFAULT_VCPUS = 2;
 export declare const DEFAULT_KERNEL_CMDLINE = "root=/dev/vda rw quiet";
+/**
+ * The guest network Virtualization.framework desks get from the helper's NAT:
+ * the same addresses QEMU's user networking uses, so they are unsurprising in
+ * a guest. Nothing outside the helper ever sees them.
+ */
+export declare const DEFAULT_VZ_GUEST_ADDRESS = "10.0.2.15";
+export declare const DEFAULT_VZ_GATEWAY_ADDRESS = "10.0.2.2";
+export declare const DEFAULT_VZ_PREFIX_LENGTH = 24;
+export declare const DEFAULT_VZ_DNS: readonly string[];
+/** Virtualization.framework always gives the guest vsock context ID 3. */
+export declare const VZ_GUEST_CID = 3;
 /**
  * Every failure this package raises. The `name` is annotated as `string`
  * rather than left to infer its literal so a subclass can narrow the meaning
@@ -20,9 +31,35 @@ export interface DeskLauncherIdentity {
     /** Host/container GID used to invoke the VMM and image tooling. */
     gid: number;
 }
+/**
+ * Which hypervisor a plan is for: Cloud Hypervisor over KVM on Linux, or
+ * Apple's Virtualization.framework through the `appkit-desk-vz` helper on an
+ * Apple silicon Mac.
+ */
+export type DeskHypervisor = 'cloud-hypervisor' | 'virtualization';
+/**
+ * The guest network of a Virtualization.framework desk. The helper runs a
+ * userspace NAT: the guest reaches the public internet and nothing else unless
+ * `allowLan` is set — no RFC 1918 space, link-local, CGNAT, or the Mac itself.
+ */
+export interface DeskGuestNetworkOptions {
+    /** Let the guest reach the Mac's LAN, link-local and CGNAT space, and the Mac. */
+    allowLan?: boolean;
+    /** The address the helper's DHCP server leases the guest. */
+    guestAddress?: string;
+    /** The helper's own address on the link: the guest's router. */
+    gatewayAddress?: string;
+    prefixLength?: number;
+    /** Resolvers the guest is handed; the first also answers DNS sent to the gateway. */
+    dns?: readonly string[];
+}
 export interface DeskLaunchPlanOptions {
     deskId: string;
+    /** Defaults to `cloud-hypervisor`. */
+    hypervisor?: DeskHypervisor;
+    /** Cloud Hypervisor only: the VMM binary. */
     vmmPath?: string;
+    /** Cloud Hypervisor only: the KVM device. */
     kvmPath?: string;
     qemuImgPath?: string;
     /** Absolute path of the kernel image the microVM boots. */
@@ -40,14 +77,27 @@ export interface DeskLaunchPlanOptions {
     overlayPath: string;
     memoryMb?: number;
     vcpus?: number;
-    /** Guest vsock context ID; must be unique among resident desks. */
+    /**
+     * Guest vsock context ID; must be unique among resident desks. Cloud
+     * Hypervisor only — a Virtualization.framework guest is always CID 3, and
+     * its vsock is private to its helper.
+     */
     vsockCid: number;
-    /** Directory holding the vsock and API control sockets. */
+    /**
+     * Directory holding the desk's control sockets. Defaults to
+     * `/run/appkit-desk` for Cloud Hypervisor and `<os tmpdir>/appkit-desk` for
+     * Virtualization.framework.
+     */
     runtimeDir?: string;
-    /** Host TAP device name; derived from the CID when omitted. */
+    /** Cloud Hypervisor only: host TAP device name; derived from the CID when omitted. */
     tapDevice?: string;
-    /** Guest MAC address; derived from the CID when omitted. */
+    /**
+     * Guest MAC address. Derived from the CID for Cloud Hypervisor, and from the
+     * desk ID for Virtualization.framework, whose restore needs the same NIC.
+     */
     macAddress?: string;
+    /** Virtualization.framework only: the helper's NAT network and fence. */
+    guestNetwork?: DeskGuestNetworkOptions;
     kernelCmdline?: string;
     launcherIdentity?: DeskLauncherIdentity;
     /**
@@ -67,17 +117,9 @@ export interface DeskLaunchPlanOptions {
      */
     restore?: boolean;
 }
-/**
- * The complete Cloud Hypervisor invocation as inspectable data. Nothing here
- * has been spawned: tests, audit logs, and readiness screens can assert on the
- * exact argv a desk would boot with.
- */
-export interface DeskLaunchPlan {
+/** What every plan carries, whichever hypervisor runs it. */
+export interface DeskLaunchPlanBase {
     deskId: string;
-    vmm: {
-        command: string;
-        args: string[];
-    };
     overlay: {
         path: string;
         basePath: string;
@@ -87,17 +129,15 @@ export interface DeskLaunchPlan {
             args: string[];
         } | null;
     };
+    /**
+     * The host Unix socket the guest's vsock is reached through, with Cloud
+     * Hypervisor's hybrid-vsock preamble: write `CONNECT <port>\n`, read
+     * `OK <n>\n`, then the stream is the guest connection.
+     */
     vsock: {
         cid: number;
         socketPath: string;
     };
-    api: {
-        socketPath: string;
-    };
-    tap: {
-        device: string;
-        mac: string;
-    };
     /** Where a memory snapshot of this desk is written, and read back from. */
     snapshot: {
         dir: string;
@@ -112,27 +152,85 @@ export interface DeskLaunchPlan {
     launcherIdentity?: DeskLauncherIdentity;
 }
 /**
- * Whether this host can run desks at all: Linux, a usable `/dev/kvm`, and the
- * Cloud Hypervisor binary. All three checks are injectable and the answer is
- * fail-closed — a host missing any of them gets no desk capability rather
- * than a degraded one.
+ * The complete Cloud Hypervisor invocation as inspectable data. Nothing here
+ * has been spawned: tests, audit logs, and readiness screens can assert on the
+ * exact argv a desk would boot with.
+ */
+export interface CloudHypervisorLaunchPlan extends DeskLaunchPlanBase {
+    hypervisor: 'cloud-hypervisor';
+    vmm: {
+        command: string;
+        args: string[];
+    };
+    api: {
+        socketPath: string;
+    };
+    tap: {
+        device: string;
+        mac: string;
+    };
+}
+/**
+ * A Virtualization.framework desk as inspectable data: what the helper is
+ * asked to boot. The helper path belongs to the backend, not the plan.
+ */
+export interface VirtualizationLaunchPlan extends DeskLaunchPlanBase {
+    hypervisor: 'virtualization';
+    /**
+     * The host Unix socket guest TCP ports are reached through, with the same
+     * preamble as `vsock`: `CONNECT <tcp port>\n` answered by `OK <n>\n` once
+     * the guest accepts, or a close with nothing written when it refuses.
+     */
+    ports: {
+        socketPath: string;
+    };
+    network: {
+        mac: string;
+        allowLan: boolean;
+        guestAddress: string;
+        gatewayAddress: string;
+        prefixLength: number;
+        dns: string[];
+    };
+}
+export type DeskLaunchPlan = CloudHypervisorLaunchPlan | VirtualizationLaunchPlan;
+/**
+ * Whether this host can run desks at all. On Linux: a usable `/dev/kvm` and
+ * the Cloud Hypervisor binary. On macOS: Apple silicon, macOS 14 or later (the
+ * first with Virtualization.framework save and restore), and an existing
+ * `appkit-desk-vz` helper at `helperPath`. Signature and entitlement are checked
+ * by macOS on execution, not by this probe. Every check is injectable and the
+ * answer is fail-closed — a host missing any of them gets no desk capability
+ * rather than a degraded one.
  */
 export declare function isDeskSupported(options?: {
     platform?: NodeJS.Platform;
     kvmPath?: string;
     vmmPath?: string;
+    /** macOS: the signed `appkit-desk-vz` helper. Required there. */
+    helperPath?: string;
+    arch?: string;
+    /** The kernel release, as `os.release()` reports it. */
+    osRelease?: string;
     pathExists?: (path: string) => boolean;
 }): boolean;
 /** Validate a desk identifier, which is used in socket paths and device names. */
 export declare function cleanDeskId(value: string): string;
+export interface DeskLaunchPlanDependencies {
+    pathExists?: (path: string) => boolean;
+    deviceExists?: (path: string) => boolean;
+}
 /**
- * Build the deterministic Cloud Hypervisor launch plan without spawning
- * anything. Fail closed: a missing `/dev/kvm`, VMM binary, kernel, base image,
+ * Build the deterministic launch plan without spawning anything. Fail closed:
+ * a missing `/dev/kvm` or VMM binary (Cloud Hypervisor), kernel, base image,
  * or overlay directory throws instead of producing a plan that cannot boot.
  */
-export declare function buildDeskLaunchPlan(options: DeskLaunchPlanOptions, dependencies?: {
-    pathExists?: (path: string) => boolean;
-    deviceExists?: (path: string) => boolean;
-}): DeskLaunchPlan;
+export declare function buildDeskLaunchPlan(options: DeskLaunchPlanOptions & {
+    hypervisor: 'virtualization';
+}, dependencies?: DeskLaunchPlanDependencies): VirtualizationLaunchPlan;
+export declare function buildDeskLaunchPlan(options: DeskLaunchPlanOptions & {
+    hypervisor?: 'cloud-hypervisor';
+}, dependencies?: DeskLaunchPlanDependencies): CloudHypervisorLaunchPlan;
+export declare function buildDeskLaunchPlan(options: DeskLaunchPlanOptions, dependencies?: DeskLaunchPlanDependencies): DeskLaunchPlan;
 export declare function cleanLauncherIdentity(identity: DeskLauncherIdentity | undefined): DeskLauncherIdentity | undefined;
 //# sourceMappingURL=plan.d.ts.map

package/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}