@braedonsaunders/appkit-desk 0.7.0 → 0.9.0

package/README.md

@@ -257,4 +257,129 @@ DESK_CHECK_IMAGE_ROOT=/data/desk-image DESK_CHECK_BASE_IMAGE=/data/desk-image/ba
 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.
+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. Set `DESK_CHECK_VIRTIOFSD` to a `virtiofsd` binary to also check a read-only share: the guest mounts it, a write fails, and a file held open across the park reads back after the restore.
+
+## Host directory shares
+
+A desk can mount host directories over virtio-fs. Pass `shares` to
+`host.start` (or `buildDeskLaunchPlan`):
+
+```ts
+const desk = await host.start({
+  deskId: 'agent-7',
+  baseImage: '/data/agent-disks/base.img',
+  overlayPath: '/data/agent-disks/overlays/agent-7.img',
+  shares: [
+    { tag: 'tools', path: '/srv/desk-tools', readOnly: true },
+    { tag: 'build', path: '/srv/builds/agent-7', readOnly: false },
+  ],
+})
+await desk.exec({ command: '/bin/sh', args: ['-c', 'mkdir -p /opt/tools && mount -t virtiofs tools /opt/tools'] })
+```
+
+A `tag` is 1–36 lowercase letters, digits or hyphens, starting with a letter or
+digit, and unique within the desk; it is the name the guest mounts. `path` is an
+absolute path to an existing host directory. `readOnly` is required. A read-only
+share is enforced by the host's file server, so remounting it read-write in the
+guest does not make it writable. The guest kernel needs virtio-fs
+(`CONFIG_VIRTIO_FS`; Debian's cloud kernels ship it as the `virtiofs` module).
+
+On Cloud Hypervisor, each share is served by its own `virtiofsd` (the Rust
+implementation, 1.13 or later). `virtiofsdPath` on the host options names the
+binary; without it the first `virtiofsd` on `PATH` is used, then
+`/usr/libexec/virtiofsd`. A desk without shares does not need `virtiofsd`. Each
+daemon runs as the launcher identity with:
+
+```sh
+virtiofsd --socket-path=<runtimeDir>/desk-<deskId>.<tag>.fs.sock --shared-dir=<path> \
+  --sandbox=<namespace|chroot> --cache=auto \
+  --migration-mode=find-paths --migration-on-error=guest-error [--readonly]
+```
+
+and the VMM gets `--fs tag=<tag>,socket=<socket>` with its memory as
+`size=<n>M,shared=on`, which vhost-user devices require; a desk without shares
+keeps private memory. `--cache=auto` lets the guest cache for about a second,
+so files the host changes under a share appear in running guests.
+`virtiofsdSandbox` picks how the daemon confines itself to the directory:
+`namespace` (the default) needs CAP_SYS_ADMIN when the launcher is root and
+unprivileged user namespaces otherwise; `chroot` needs root and suits a
+container that cannot create namespaces. Both prevent symlink escapes. The
+backend starts every daemon and waits for its socket before starting the VMM,
+on a boot and on a restore, and stops the daemons after the VMM. A daemon that
+exits while its VMM runs stops the VMM, so the desk is lost rather than left
+with a share that no longer answers. `virtiofsd` also exits when its VMM
+disconnects. The share socket path must fit in 107 bytes.
+
+On Virtualization.framework, each share is a
+`VZVirtioFileSystemDeviceConfiguration` with a `VZSingleDirectoryShare`, and the
+framework enforces `readOnly`. `virtiofsdPath` and `virtiofsdSandbox` are
+refused there. When Virtualization.framework reports that a configuration
+cannot be saved, the desk parks by shutting down, as for any other device.
+
+Parking keeps a desk's shares with its memory. The backend records them in
+`shares.json` beside the snapshot, and a restore uses that record instead of the
+start options: a snapshot holds its devices, so a share added since joins the
+desk at its next cold boot (`host.shutdown` forces one), and a backend refuses a
+restore plan whose shares differ from the record. A recorded share whose
+directory no longer exists fails the restore; the host discards the snapshot,
+cold boots with the current shares, and reports it in `lastError`. A snapshot
+holds no share contents. On Cloud Hypervisor it carries each daemon's state,
+which the new daemon loads on restore by reopening every file and directory the
+guest held by its path, so open files survive. Paths are the link: a file the
+host unlinks or moves while the desk is parked returns errors to the guest for
+that file only, and a file the host puts at its path is the one the guest gets.
+
+## 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: {
@@ -163,6 +184,10 @@ export interface CloudHypervisorBackendOptions {
     reconnectRetryDelayMs?: number;
     killGraceMs?: number;
     guestAgentPort?: number;
+    /** Whether a share daemon's socket exists yet; injectable for tests. */
+    pathExists?: (path: string) => boolean;
+    /** Removes a stale share socket before its daemon starts; injectable for tests. */
+    removeFile?: (path: string) => Promise<void>;
 }
 export declare function createCloudHypervisorBackend(options?: CloudHypervisorBackendOptions): DeskBackend;
 /**

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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"}