@braedonsaunders/appkit-desk 0.6.0 → 0.8.0

package/README.md

@@ -112,6 +112,12 @@ stops, the disk persists, applications cold-start on `resume`. Keep-alive jobs
 die with the lease, and their termination is recorded as `job_exit` so no
 process ever runs where an operator cannot see it.
 
+`host.shutdown(deskId)` is a restart, not a destroy: a resident desk is synced
+and shut down instead of parked, a parked desk's memory snapshot is discarded,
+and the overlay stays, so the next `start` or `resume` cold boots from disk.
+Use it when a desk must come back fresh — new memory or vCPU settings, or a
+guest wedged in a way a resume would bring straight back.
+
 Residency is bounded by a hard capacity cap. Starts beyond the cap queue FIFO
 rather than overcommitting host memory. `host.stats()` reports
 `{ resident, queued, capacity, suspended, lastStartedAt, lastSuspendedAt,
@@ -179,7 +185,8 @@ append-only record that cannot be edited afterward.
 
 `onEvent` receives a closed union — `shell_command`, `app_launch`, `click`,
 `type`, `key`, `scroll`, `drag`, `window_focus`, `screen_open`,
-`screen_close`, `handover_begin`, `handover_end`, `job_start`, `job_exit` —
+`screen_close`, `handover_begin`, `handover_end`, `job_start`, `job_exit`,
+`snapshot_cpu_fallback` —
 each stamped with `deskId` and an ISO timestamp. The union is defined here so
 the consumer's ledger and this package agree on the taxonomy; persistence is
 entirely the consumer's concern.
@@ -231,3 +238,78 @@ masking boundary changes.
 Do not fall back to unconfined execution when this package reports an
 unsupported host. A deployment without KVM loses the desk ability entirely —
 the same fail-closed posture as the rest of AppKit.
+
+## Routed guest networking and TCP services
+
+`deskNetworkIdentity(index)` returns a deterministic TAP name and MAC address. `createDeskNetwork({ gateway, dns, egress, chainPrefix?, allowHostPorts?, prefixLength?, runner?, enableForwarding? })` provides routed point-to-point TAP setup. Set `egress: { mode: 'open' }` to masquerade guest-originated IPv4 traffic for arbitrary TCP and UDP; IPv6 traffic on the TAP is blocked with `ip6tables` so it cannot bypass host isolation; new inbound forwarded connections are dropped. Set `egress: { mode: 'proxied', httpProxyPort, httpsProxyPort }` to transparently redirect HTTP and HTTPS to proxy listeners, pin DNS to the supplied resolver, and drop other guest egress. The proxy supplies destination policy. Both modes drop new connections to host services, except TCP and UDP ports explicitly listed in `allowHostPorts` on the gateway address; proxied mode also permits its proxy listeners. Established replies to host-initiated guest connections are accepted.
+
+The default iptables chain prefix is `desk`. Existing deployments using the `bh` chains must supply `chainPrefix: 'bh'` to retain those names during a rolling upgrade and avoid orphaning the old rules. `ensure({ tap, guest })` must finish before boot; `teardown({ tap, guest })` removes its rules and TAP after the VM stops. Configure Linux IPv4 forwarding, NET_ADMIN, `ip`, and `iptables` in the host namespace; open mode also requires `ip6tables`. When changing egress modes, tear down the old mode before installing the new one. `configureGuest(desk, { tap, guest })` configures the guest interface, route, and resolver through exec. `syncDeskGuestClock(desk, now?)` sets the guest clock after wake. Failures are reported to the caller. Operations on one TAP are serialized within the network instance; use one instance per namespace. Rule replacement uses multiple iptables commands and is not atomic: call `ensure` before the VM starts, and do not refresh rules on a live TAP.
+
+Supply `network: { tapDevice, macAddress, guestAddress }` to `host.start`, then `await desk.connect(port)` returns a Node `Duplex` TCP stream to the guest. The caller owns the stream; suspension closes it. A service must listen on the guest interface, and its protocol and authentication remain the application's responsibility. `connectGuest` on host options injects a dialer for testing.
+
+With `parkWithMemory`, new snapshots carry a host CPU signature. A changed signature skips restore and cold boots; Cloud Hypervisor's specific incompatible-CPUID restore error also triggers a cold boot. These outcomes increment `stats().snapshotCpuFallbacks`, set `lastSnapshotCpuFallback`, and emit `snapshot_cpu_fallback`, rather than setting `lastError`. Existing snapshots without a signature are attempted normally. Signatures are conservative CPU identity and feature fingerprints, not a guarantee of CPUID compatibility; a cold boot loses the parked process state. Keep snapshots and their overlays together.
+
+For a disposable real-host check, provide a guest image with the desk agent and Python 3, Cloud Hypervisor, KVM, and a free TAP name and IP pair. Run from the repository root in the target network namespace with privileges to manage TAP and iptables:
+
+```sh
+DESK_CHECK_TAP=dsk9001 DESK_CHECK_GUEST=172.30.0.2 DESK_CHECK_GATEWAY=172.30.0.1 \
+DESK_CHECK_IMAGE_ROOT=/data/desk-image DESK_CHECK_BASE_IMAGE=/data/desk-image/base.img \
+DESK_CHECK_TMPDIR=/data/tmp pnpm --filter @braedonsaunders/appkit-desk exec tsx scripts/check-kvm.mts
+```
+
+Set `DESK_CHECK_KERNEL_CMDLINE` for images that require a custom root device. The check creates and removes a disposable VM, overlay, snapshot, TAP and firewall rules. It verifies a guest HTTP stream before and after memory restore; it does not verify the proxy or cross-CPU migration. Choose addresses that do not overlap existing routes.
+
+## macOS Virtualization.framework backend
+
+On Apple silicon with macOS 14 or later, a host can supply a signed
+`appkit-desk-vz` helper to `createVirtualizationBackend` and pass that backend
+into `createDeskHost`:
+
+```ts
+import { createDeskHost, createVirtualizationBackend, isDeskSupported } from '@braedonsaunders/appkit-desk'
+
+const helperPath = '/opt/appkit/bin/appkit-desk-vz'
+if (!isDeskSupported({ helperPath })) throw new Error('This host cannot run desks.')
+const backend = createVirtualizationBackend({ helperPath })
+const host = createDeskHost({
+  imageRoot: '/var/lib/appkit/desk',
+  backend,
+  guestNetwork: { allowLan: false },
+  ports,
+})
+```
+
+The guest needs an arm64 Linux kernel, raw base image and the same desk guest
+agent as the Linux backend. Use the kernel command line appropriate to the
+image. Per-desk disks use macOS `cp -c`; provision the overlay directory on a
+filesystem that supports cloning. The helper creates a userspace IPv4 network
+with DHCP, defaults to `10.0.2.15/24` and gateway `10.0.2.2`, and blocks
+private, link-local, shared and host addresses by default. RFC 5737 documentation
+subnets (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) are always blocked,
+including when LAN access is allowed. Set `allowLan` only
+when the host policy explicitly permits local network access. `DeskHandle.connect`
+uses the helper's TCP relay; no routable guest IP on the Mac is required.
+
+The npm package includes the Swift source under `vz/`. Build it on macOS with
+Xcode and `vz/build.sh`; the script signs with the required virtualization
+entitlement. Its default ad hoc signature is for local use. Distributors must
+sign with their own Developer ID (`APPKIT_CODESIGN_IDENTITY`) and handle
+notarization and distribution. The caller supplies the absolute installed
+helper path; installation does not download or execute a binary. Save and
+restore use a stable desk MAC and machine identifier; the host removes the
+snapshot while the restored VM is paused before resuming it. The userspace
+network is recreated on restore, so existing TCP and UDP flows must reconnect.
+
+For a disposable macOS integration check, supply a prepared guest image with
+its desk agent and Python 3, its matching `vmlinux` and `initrd`, and the signed
+helper. In a source checkout, run `packages/desk/scripts/check-vz.mts` with `DESK_CHECK_IMAGE_ROOT`,
+`DESK_CHECK_BASE_IMAGE`, and `DESK_CHECK_VZ_HELPER`; set
+`DESK_CHECK_KERNEL_CMDLINE` if the image uses a different root device. The
+check creates a temporary guest and tests guest execution, a private-host
+network fence, guest TCP access, and memory save/restore. It removes the guest
+and its temporary files on exit.
+
+For clients that require a local TCP URL, `await listenDeskPort(desk, port)`
+returns a loopback-only `{ host, port, close }` listener. Each incoming
+connection opens a guest stream through `desk.connect`; call `close()` when the
+lease ends to close the listener and its connections.

package/backend.d.ts

@@ -1,18 +1,19 @@
 /**
- * The backend port and its default Cloud Hypervisor implementation.
+ * The backend port.
  *
  * `DeskBackend` is the seam that keeps the package testable without a
  * hypervisor: the host asks a backend to boot a `DeskLaunchPlan` and gets a
  * `DeskMachine` — a request/response channel to the in-guest agent plus an
  * event subscription. CI and non-KVM developer machines inject an in-memory
- * fake; production uses `cloudHypervisorBackend`, whose process-spawning glue
- * is deliberately thin because everything that can be pure lives in the plan
- * builder and the protocol module.
+ * fake; production uses `cloudHypervisorBackend` on Linux or
+ * `createVirtualizationBackend` on an Apple silicon Mac, whose process glue is
+ * deliberately thin because everything that can be pure lives in the plan
+ * builder, the protocol module, and the shared guest channel.
  */
-import { type ChildProcess } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 import type { Duplex } from 'node:stream';
-import { DeskError, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan.js';
-import { type GuestCommand, type GuestEventMessage } from './protocol.js';
+import { DeskError, type DeskHypervisor, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan.js';
+import type { GuestCommand, GuestEventMessage } from './protocol.js';
 /**
  * A request that was in flight when the guest connection dropped.
  *
@@ -88,6 +89,16 @@ export interface DeskMachine {
      * misbehaves for reasons nobody can find.
      */
     onConnectionChange?(listener: (change: DeskConnectionChange) => void): () => void;
+    /**
+     * Open a TCP stream from the host to `port` on the guest.
+     *
+     * Optional: a backend whose guest has a routable address (Cloud Hypervisor's
+     * TAP) leaves this out and the host dials the guest address directly. A
+     * backend whose guest sits behind a userspace NAT (Virtualization.framework)
+     * provides it, because there is no address on the Mac to dial. Rejects with
+     * `DeskError` when the guest refuses or does not answer.
+     */
+    connect?(port: number): Promise<Duplex>;
     /** Stop the VM. Idempotent; resolves once the VMM process has exited. */
     shutdown(): Promise<void>;
     /**
@@ -123,6 +134,16 @@ export interface DeskBootHooks {
     onRestored?: () => Promise<void>;
 }
 export interface DeskBackend {
+    /**
+     * Which hypervisor this backend boots, and so which plan the host builds
+     * for it. Absent means Cloud Hypervisor.
+     */
+    readonly hypervisor?: DeskHypervisor;
+    /**
+     * The binary the backend launches — the VMM or the helper — for readiness
+     * reporting. Optional; `verifyDeskHost` falls back to its own option.
+     */
+    readonly vmmPath?: string;
     boot(plan: DeskLaunchPlan, hooks?: DeskBootHooks): Promise<DeskMachine>;
 }
 export type DeskProcessLauncher = (command: string, args: readonly string[], options: {

package/backend.d.ts.map

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