Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(lume): automate SIP changes through macOS Recovery (#2165)
Francesco Bonaccia56193f93e87
diff --git a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdxindex 51ad10ac6b..29507d286a 100644--- a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx+++ b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx@@ -29,6 +29,13 @@ particular macOS release exposes. Disk setup writes the desired guest statedirectly and keeps the verification step small: Lume checks that the guestboots and accepts SSH.+## Boot policy changes use Recovery++Offline setup can change guest files, but it cannot sign Apple silicon boot+policy. SIP changes therefore use the VM's paired Recovery environment and a+normal boot verification. Read [How SIP works in Lume+VMs](/concepts/how-sip-works-in-lume-vms) for the policy model.+## Presets and imagesThe `tahoe` and `sequoia` presets use the same offline patcher. Tahoe is the@@ -44,4 +51,5 @@ required for unattended setup.- [Create your first local macOS VM](/tutorials/create-your-first-lume-vm)- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm)+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)- [Lume CLI reference](/reference/lume/cli-reference)diff --git a/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdxnew file mode 100644index 0000000000..28615c19e3--- /dev/null+++ b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx@@ -0,0 +1,80 @@+---+title: How SIP works in Lume VMs+description: Understand signed LocalPolicy state, paired Recovery, and why Lume verifies SIP after reboot.+---++System Integrity Protection (SIP) on an Apple silicon VM is part of a signed+boot policy. Changing files on the macOS Data volume cannot change that policy.++## SIP state is a signed LocalPolicy++Apple silicon stores SIP configuration in a LocalPolicy signed by the Secure+Enclave. Virtualization.framework provides the corresponding security service+for a macOS VM.++The policy belongs to a larger paired state:++- `disk.img` contains macOS, personalized boot files, and Recovery;+- `nvram.bin` contains auxiliary security and anti-replay state; and+- the VM configuration identifies the virtual hardware that boots them.++Copying or editing one part does not mint a valid policy for another VM.++## Offline setup and SIP use different paths++Lume's unattended setup mounts the Data volume and writes account, SSH,+autologin, and power settings. Those settings are ordinary guest files, so an+offline patcher can prepare them without driving Setup Assistant.++SIP is different because the policy must be signed from the VM's paired+Recovery environment. Editing `disk.img` or patching bytes in `nvram.bin`+cannot produce a valid signature.++## Why `lume sip` uses Recovery++`lume sip` coordinates three VM sessions:++1. A normal boot checks that the requested administrator account works over+ SSH.+2. A Recovery boot opens Terminal over a temporary VNC session and runs+ `csrutil enable` or `csrutil disable`.+3. A final normal boot runs `csrutil status` over SSH.++During Recovery, Lume checks the named account prompt and reads the terminal+result with OCR before it stops the VM. Tahoe Recovery does not always halt+after its shutdown command, so Lume can stop that exact `lume run` process+after a grace period. It waits for the VM to report `stopped` before the final+boot.++## Verification happens after reboot++The Recovery message confirms that `csrutil` accepted the policy change. The+normal boot proves that the VM can use the new policy.++Lume accepts only the canonical top-level status:++```text+System Integrity Protection status: enabled.+```++or:++```text+System Integrity Protection status: disabled.+```++A customized policy can list enabled and disabled components at the same time.+Lume rejects that output instead of inferring a state from one component line.++## Clones keep paired files together++`lume clone` copies the VM disk and auxiliary storage as a pair. This is the+supported way to reproduce a prepared seed. Copying only `disk.img` loses the+matching security state; copying only `nvram.bin` loses the matching boot+files.++## Related pages++- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)+- [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works)+- [Lume limits](/reference/lume/limits#sip-automation)diff --git a/docs/content/docs/concepts/index.mdx b/docs/content/docs/concepts/index.mdxindex 44cf494eff..4f317ee608 100644--- a/docs/content/docs/concepts/index.mdx+++ b/docs/content/docs/concepts/index.mdx@@ -5,4 +5,4 @@ description: "Understand the design ideas behind Cua and how its main pieces fitUse these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable computer.-Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) when you need the local VM setup model.+Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) for the local VM setup model, and [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms) for signed boot-policy changes.diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.jsonindex f4113c0ce2..55e4f5d72f 100644--- a/docs/content/docs/concepts/meta.json+++ b/docs/content/docs/concepts/meta.json@@ -1 +1 @@-{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work", "how-lume-unattended-setup-works"] }+{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work", "how-lume-unattended-setup-works", "how-sip-works-in-lume-vms"] }diff --git a/docs/content/docs/how-to-guides/lume/change-sip.mdx b/docs/content/docs/how-to-guides/lume/change-sip.mdxnew file mode 100644index 0000000000..615ea0791b--- /dev/null+++ b/docs/content/docs/how-to-guides/lume/change-sip.mdx@@ -0,0 +1,111 @@+---+title: Change SIP on a macOS VM+description: Disable or enable System Integrity Protection from paired macOS Recovery and verify the result.+---++Use `lume sip` to change System Integrity Protection (SIP) on a stopped macOS+VM. Lume runs `csrutil` in the VM's paired Recovery environment and verifies+the result after a normal boot.++For the policy model behind this workflow, read [How SIP works in Lume+VMs](/concepts/how-sip-works-in-lume-vms).++## Before you start++The VM must:++- run macOS;+- be stopped;+- have a working administrator account; and+- have Remote Login enabled.++VMs created with Lume's unattended setup meet these requirements. Their+initial username and password are both `lume`.++Install the optional Recovery VNC driver:++```bash+python3 -m pip install --user vncdotool+```++Recovery input currently supports administrator passwords made from lowercase+ASCII letters, digits, and hyphens. The Recovery password prompt must name the+account passed with `--admin-user`.++## Disable SIP++With the default `lume` account, run:++```bash+lume sip off macos-tahoe+```++Confirm the change when prompted. Lume validates the account, changes the+policy in Recovery, boots normally to run `csrutil status`, and leaves the VM+stopped. A successful run ends with:++```text+System Integrity Protection status: disabled.+SIP is disabled.+```++For another administrator account, enter its password without exposing it in+the process arguments:++```bash+lume sip off macos-tahoe \+ --admin-user admin \+ --admin-password-stdin+```++For non-interactive use, provide confirmation with `--yes` so the password is+the only line read from standard input:++```bash+printf '%s\n' "$LUME_ADMIN_PASSWORD" | \+ lume sip off macos-tahoe \+ --admin-user admin \+ --admin-password-stdin \+ --yes+```++## Enable SIP++Run the same command with `on`:++```bash+lume sip on macos-tahoe \+ --admin-user admin \+ --admin-password-stdin+```++A successful run ends with the canonical enabled status and leaves the VM+stopped.++## Prepare a reusable SIP-disabled VM++Change SIP on a stopped seed, then clone it:++```bash+lume sip off macos-tahoe-seed --yes+lume clone macos-tahoe-seed macos-tahoe-worker-001+```++Lume copies `disk.img` and `nvram.bin` together. Do not replace either file+independently because the signed policy, personalized boot files, and+anti-replay state belong to one paired VM state.++Boot a worker and inspect its policy when you need an extra check:++```bash+lume run --no-display macos-tahoe-worker-001+lume ssh macos-tahoe-worker-001 'csrutil status'+lume stop macos-tahoe-worker-001+```++## Related pages++- [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms)+- [Manage local Lume VMs](/how-to-guides/lume/manage-vms)+- [Lume limits](/reference/lume/limits#sip-automation)+- [Lume CLI reference](/reference/lume/cli-reference#lume-sip)diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdxindex a56d41269f..400baecb53 100644--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx@@ -52,6 +52,7 @@ You can also download the `lume.pkg.tar.gz` archive from the [latest release](ht- [Create your first local VM](/tutorials/create-your-first-lume-vm): follow the Tahoe happy path from IPSW to SSH.- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm): create, run, inspect, and remove a local VM.- [Manage local VMs](/how-to-guides/lume/manage-vms): share files, use storage locations, and clone disks.+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip): change the signed policy from paired Recovery.- [Serve the Lume API](/how-to-guides/lume/serve-api): run the local HTTP API for tools and scripts.- [Use Lume with MCP](/how-to-guides/lume/use-mcp-server): connect an AI client to local VM tools.- [Lume CLI reference](/reference/lume/cli-reference): inspect every command and option.diff --git a/docs/content/docs/how-to-guides/lume/manage-vms.mdx b/docs/content/docs/how-to-guides/lume/manage-vms.mdxindex ed0e860686..637b742fc5 100644--- a/docs/content/docs/how-to-guides/lume/manage-vms.mdx+++ b/docs/content/docs/how-to-guides/lume/manage-vms.mdx@@ -102,3 +102,6 @@ lume delete macos-tahoe-backupmacOS VM disks can be sparse. The configured capacity and the host space usedby the disk can therefore differ.++To disable or enable System Integrity Protection, follow [Change SIP on a+macOS VM](/how-to-guides/lume/change-sip).diff --git a/docs/content/docs/how-to-guides/lume/meta.json b/docs/content/docs/how-to-guides/lume/meta.jsonindex f5fd69296b..a59cb1648b 100644--- a/docs/content/docs/how-to-guides/lume/meta.json+++ b/docs/content/docs/how-to-guides/lume/meta.json@@ -1 +1 @@-{ "title": "Lume", "pages": ["install-lume", "create-vanilla-vm", "manage-vms", "serve-api", "use-mcp-server"] }+{ "title": "Lume", "pages": ["install-lume", "create-vanilla-vm", "manage-vms", "change-sip", "serve-api", "use-mcp-server"] }diff --git a/docs/content/docs/reference/lume/cli-reference.mdx b/docs/content/docs/reference/lume/cli-reference.mdxindex 7dc759e7ec..f29ec49041 100644--- a/docs/content/docs/reference/lume/cli-reference.mdx+++ b/docs/content/docs/reference/lume/cli-reference.mdx@@ -50,24 +50,6 @@ Create a new virtual machine| `--debug` | false | Compatibility flag; ignored by offline setup. || `--no-display` | false | Compatibility flag; offline setup verifies headlessly. |-### lume clone--Clone an existing virtual machine--**Arguments:**--| Name | Type | Required | Description |-| ---- | ---- | -------- | ----------- |-| `<name>` | String | Yes | Name of the source VM |-| `<new-name>` | String | Yes | Name for the cloned VM |--**Options:**--| Name | Type | Default | Description |-| ---- | ---- | ------- | ----------- |-| `--source-storage` | String | - | Source VM storage location |-| `--dest-storage` | String | - | Destination VM storage location |-### lume runRun a virtual machine@@ -135,8 +117,37 @@ Delete a virtual machine| ---- | ------- | ----------- || `--force` | false | Force deletion without confirmation |+### lume clone++Clone an existing virtual machine++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<name>` | String | Yes | Name of the source VM |+| `<new-name>` | String | Yes | Name for the cloned VM |++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--source-storage` | String | - | Source VM storage location |+| `--dest-storage` | String | - | Destination VM storage location |+## VM Information and Configuration+### lume ls++List virtual machines++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `-f, --format` | String | text | Output format (json or text) |+| `--storage` | String | - | Filter by storage location name |+### lume getGet detailed information about a virtual machine@@ -174,18 +185,17 @@ Set new values for CPU, memory, and disk size of a virtual machine| `--display` | String | - | New display resolution || `--storage` | String | - | VM storage location to use |-### lume ls+## Image Management-List virtual machines+### lume images++List available macOS images from local cache**Options:**| Name | Type | Default | Description || ---- | ---- | ------- | ----------- |-| `-f, --format` | String | text | Output format (json or text) |-| `--storage` | String | - | Filter by storage location name |--## Image Management+| `--organization` | String | trycua | Organization to list images for |### lume pull@@ -235,15 +245,32 @@ Push a macOS VM to an OCI-compatible registry| `--dry-run` | false | Prepare files without uploading || `--reassemble` | true | Verify integrity by reassembling chunks |-### lume images+### lume convert-List available macOS images from local cache+Convert a legacy Lume image to OCI-compliant format++**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<source-image>` | String | Yes | Source image to convert (legacy format, for example macos-tahoe:latest) |+| `<target-image>` | String | Yes | Target image to push in OCI format (name:tag) |**Options:**| Name | Type | Default | Description || ---- | ---- | ------- | ----------- |-| `--organization` | String | trycua | Organization to list images for |+| `--additional-tags` | [String] | - | Additional tags for the OCI image |+| `--registry` | String | ghcr.io | Registry to pull from and push to |+| `--organization` | String | trycua | Registry organization |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--verbose` | false | Enable verbose logging |+| `--dry-run` | false | Prepare files without uploading |+| `--single-layer` | false | Push one kubelet-compatible disk layer |### lume ipsw@@ -253,7 +280,7 @@ Get macOS restore image IPSW URLRemove cached images-## Guest Access and Setup+## Guest Access and Security### lume ssh@@ -301,17 +328,36 @@ Prepare unattended macOS setup| `--no-display` | false | Compatibility flag; offline setup verifies headlessly || `--debug` | false | Compatibility flag; ignored by offline setup |-## Configuration and Server+### lume sip-### lume serve+Enable or disable System Integrity Protection on a macOS VM-Start the VM management server+**Arguments:**++| Name | Type | Required | Description |+| ---- | ---- | -------- | ----------- |+| `<state>` | String | Yes | Desired SIP state: on or off |+| `<name>` | String | Yes | Name of the virtual machine |**Options:**| Name | Type | Default | Description || ---- | ---- | ------- | ----------- |-| `--port` | Int | 7777 | Port to listen on |+| `--admin-user` | String | lume | Administrator username in the guest |+| `--admin-password` | String | - | Administrator password in the guest; prefer --admin-password-stdin |+| `--screenshot-dir` | String | - | Directory for Recovery framebuffer screenshots |+| `--vnc-port` | Int | 5999 | Port for the temporary Recovery VNC server |+| `--storage` | String | - | VM storage location |+| `--timeout` | Int | 900 | Overall timeout in seconds |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `-y, --yes` | false | Skip the interactive confirmation prompt |+| `--admin-password-stdin` | false | Read one administrator-password line from standard input without echo |++## Configuration and Server### lume config@@ -331,6 +377,16 @@ Get or set lume configuration- `lume config cache enable` - Enable image caching- `lume config cache disable` - Disable image caching+### lume serve++Start the VM management server++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--port` | Int | 7777 | Port to listen on |+### lume logsView lume serve logs@@ -366,6 +422,24 @@ Check for a Lume update and optionally apply it| `--apply` | false | Apply the update by re-running the official installer || `--json` | false | Emit the structured update-state payload as JSON |+## Developer Tools++### lume dump-docs++Output CLI and API documentation as JSON for tooling and integrations++**Options:**++| Name | Type | Default | Description |+| ---- | ---- | ------- | ----------- |+| `--type` | String | cli | Documentation type: cli, api, or all |++**Flags:**++| Name | Default | Description |+| ---- | ------- | ----------- |+| `--pretty` | false | Pretty-print JSON output |+## Global OptionsThese options are available for all commands:diff --git a/docs/content/docs/reference/lume/limits.mdx b/docs/content/docs/reference/lume/limits.mdxindex d7bcc59b12..8e56435c02 100644--- a/docs/content/docs/reference/lume/limits.mdx+++ b/docs/content/docs/reference/lume/limits.mdx@@ -61,6 +61,21 @@ lume get macos-tahoelume ssh macos-tahoe 'id -un'```+## SIP automation++- `lume sip` supports stopped macOS VMs only.+- The VM must have a working administrator account and Remote Login enabled.+- The optional `vncdotool` package provides Recovery VNC input.+- Recovery input accepts administrator passwords made from lowercase ASCII+ letters, digits, and hyphens.+- The account named by `--admin-user` must match the Recovery password prompt.+- Tahoe is the currently verified Recovery workflow.+- The command leaves the VM stopped after a successful policy change.+- If Recovery does not halt during its grace period, Lume stops that exact run+ process and requires a normal-boot `csrutil status` verification.+- Customized SIP policies are rejected because they do not have one canonical+ enabled or disabled state.+## Disk allocationmacOS VM disks use sparse files. The configured disk capacity describes thediff --git a/libs/lume/README.md b/libs/lume/README.mdindex 61dfb00b8b..5c56bc3633 100644--- a/libs/lume/README.md+++ b/libs/lume/README.md@@ -25,3 +25,14 @@ tracked in [#2155](https://github.com/trycua/cua/issues/2155).To use the other built-in preset, replace `tahoe` with `sequoia` in the`--unattended` option and choose a matching VM name.++## Optional dependencies++The `lume sip` command uses `vncdotool` to control macOS Recovery over VNC.+Install it only if you need to enable or disable SIP:++```bash+pip3 install vncdotool+```++Other Lume commands do not require this package.diff --git a/libs/lume/src/Commands/Convert.swift b/libs/lume/src/Commands/Convert.swiftindex a232feada3..38aaca7032 100644--- a/libs/lume/src/Commands/Convert.swift+++ b/libs/lume/src/Commands/Convert.swift@@ -9,11 +9,11 @@ struct Convert: AsyncParsableCommand {under a new name/tag, then removes the temporary local VM.Example:- lume convert macos-sequoia:latest trycua/macos-sequoia:latest-oci+ lume convert macos-tahoe:latest trycua/macos-tahoe:latest-oci""")- @Argument(help: "Source image to convert (legacy format, e.g. macos-sequoia:latest)")+ @Argument(help: "Source image to convert (legacy format, e.g. macos-tahoe:latest)")var sourceImage: String@Argument(help: "Target image to push in OCI format (format: name:tag)")diff --git a/libs/lume/src/Commands/Sip.swift b/libs/lume/src/Commands/Sip.swiftnew file mode 100644index 0000000000..bd28dc6dc6--- /dev/null+++ b/libs/lume/src/Commands/Sip.swift@@ -0,0 +1,629 @@+import ArgumentParser+import Darwin+import Foundation++/// `lume sip <on|off> <vm>`+///+/// Changes SIP from paired recoveryOS, where Apple permits LocalPolicy+/// downgrades. Recovery has no supported command channel, so the workflow+/// drives its Terminal over the VM's transient VNC server and then verifies+/// the result over SSH after a normal boot.+struct Sip: AsyncParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "sip", abstract: "Enable or disable System Integrity Protection on a macOS VM",+ discussion: """+ Boots a stopped VM normally to validate the admin credentials, then+ boots paired recoveryOS and runs `csrutil disable` (or `enable`) in+ Terminal over VNC. After confirming the signed policy result, Lume+ stops Recovery and boots normally once more to verify the result.++ The VM must already have an admin account and Remote Login enabled.+ VMs created with unattended setup use lume/lume by default.++ Prefer --admin-password-stdin so the guest password does not appear+ in the Lume process arguments. --admin-password remains available+ for interactive convenience but can be observed by other processes.++ Prerequisite: vncdotool (pip3 install vncdotool).++ Examples:+ lume sip off my-vm --yes+ printf 'secret\\n' | lume sip on my-vm --yes \\+ --admin-user alice --admin-password-stdin+ """)++ enum State: String, ExpressibleByArgument, Sendable { case on, off }++ @Argument(help: "Desired SIP state: on or off") var state: State++ @Argument(help: "Name of the virtual machine", completion: .custom(completeVMName)) var name: String++ @Flag(name: [.short, .long], help: "Skip the interactive confirmation prompt") var yes: Bool = false++ @Option(name: .customLong("admin-user"), help: "Admin username in the guest") var adminUser: String = "lume"++ @Option(+ name: .customLong("admin-password"),+ help: "Admin password in the guest. Prefer --admin-password-stdin; defaults to lume") var adminPassword: String?++ @Flag(+ name: .customLong("admin-password-stdin"), help: "Read one admin-password line from standard input without echo"+ ) var adminPasswordStdin: Bool = false++ @Option(name: .customLong("screenshot-dir"), help: "Save step-by-step framebuffer PNGs here for debugging")+ var screenshotDir: String?++ @Option(name: .customLong("vnc-port"), help: "TCP port for the transient recovery VNC server")+ var vncPort: Int = 5999++ @Option(name: .customLong("storage"), help: "VM storage location") var storage: String?++ @Option(help: "Overall timeout in seconds") var timeout: Int = 900++ @MainActor func run() async throws {+ TelemetryClient.shared.record(event: "lume_sip")+ guard timeout > 0 else { throw SipError.invalidTimeout(timeout) }++ let controller = LumeController()+ let details = try loadInitialDetails(controller: controller)+ try Self.validateInitialState(details, expectedName: name)++ if !yes { try confirmChange() }++ let password = try resolvedAdminPassword()+ try Self.validateVNCPasswordCharacters(password)+ let vncdo = try Self.requireVNCExecutable(VNCDriver.locateVncdo())+ Logger.info("Using vncdotool", metadata: ["path": vncdo])++ let selfExecutable = resolvedSelfExecutable()+ let deadline = SipDeadline(seconds: timeout)++ try await preflightCredentials(+ controller: controller, executable: selfExecutable, password: password, deadline: deadline)+ try await changePolicyInRecovery(+ controller: controller, executable: selfExecutable, vncdo: vncdo, password: password, deadline: deadline)+ try await verifyPolicy(+ controller: controller, executable: selfExecutable, password: password, deadline: deadline)+ }++ @MainActor private func preflightCredentials(+ controller: LumeController, executable: String, password: String, deadline: SipDeadline+ ) async throws {+ Logger.info("Booting normally to validate admin credentials", metadata: ["vm": name])+ let child = try SipChildProcess(+ executable: executable, arguments: runArguments(recovery: false), label: "credential-preflight")++ do {+ try child.start()+ let details = try await waitForSSHReady(+ controller: controller, child: child, context: "credential preflight", deadline: deadline,+ maxSeconds: 300)+ guard let ip = details.ipAddress else {+ throw SipError.credentialPreflightFailed("VM did not report an IP address")+ }++ let ssh = SSHClient(host: ip, port: 22, user: adminUser, password: password)+ do {+ let result = try await ssh.execute(+ command: "true", timeout: try deadline.remaining(upTo: 30, operation: "credential preflight"))+ guard result.exitCode == 0 else {+ throw SipError.credentialPreflightFailed("SSH command exited with status \(result.exitCode)")+ }+ } catch let error as SipError { throw error } catch {+ throw SipError.credentialPreflightFailed(+ "SSH authentication failed for '\(adminUser)': \(error.localizedDescription)")+ }++ Logger.info("Admin credential preflight passed", metadata: ["vm": name])+ try await stopNormalBoot(+ child: child, controller: controller, deadline: deadline, operation: "credential preflight")+ child.cleanup()+ } catch {+ await child.terminateAndWait()+ child.cleanup()+ throw error+ }+ }++ @MainActor private func changePolicyInRecovery(+ controller: LumeController, executable: String, vncdo: String, password: String, deadline: SipDeadline+ ) async throws {+ let vncPassword = Self.makeVNCPassword()+ Logger.info("Booting recovery", metadata: ["vm": name, "vnc_port": "\(vncPort)"])+ let child = try SipChildProcess(+ executable: executable, arguments: runArguments(recovery: true, vncPassword: vncPassword), label: "recovery"+ )++ do {+ try child.start()+ let driver = VNCDriver(+ vncdo: vncdo, host: "127.0.0.1", port: vncPort, password: vncPassword, screenshotDir: screenshotDir)+ let heartbeat = { try child.ensureRunning(context: "recovery boot", redacting: [vncPassword]) }+ let automator = SipRecoveryAutomator()+ try await automator.perform(+ driver: driver, state: state, adminUser: adminUser, adminPassword: password, heartbeat: heartbeat,+ timeout: { limit, operation in try deadline.remaining(upTo: limit, operation: operation) })++ Logger.info("Waiting for recovery to shut down")+ do {+ try await waitForProcessExit(+ child, deadline: deadline, maxSeconds: 60,+ context: "recovery shutdown; SIP state may not have been committed", redacting: [vncPassword])+ } catch SipError.childProcessTimedOut {+ Logger.info(+ "Recovery did not halt after committing the policy; stopping its run process",+ metadata: ["vm": name])+ await child.terminateAndWait()+ guard !child.isRunning else {+ throw SipError.childProcessTimedOut(+ context: "recovery shutdown fallback", output: child.outputTail(redacting: [vncPassword]))+ }+ }+ try await waitForStoppedState(controller: controller, deadline: deadline, operation: "recovery shutdown")+ child.cleanup()+ } catch {+ await child.terminateAndWait()+ child.cleanup()+ throw error+ }+ }++ @MainActor private func verifyPolicy(+ controller: LumeController, executable: String, password: String, deadline: SipDeadline+ ) async throws {+ Logger.info("Booting normally to verify SIP state")+ let child = try SipChildProcess(+ executable: executable, arguments: runArguments(recovery: false), label: "verification")++ do {+ try child.start()+ let details = try await waitForSSHReady(+ controller: controller, child: child, context: "verification boot", deadline: deadline, maxSeconds: 300)+ guard let ip = details.ipAddress else {+ throw SipError.verificationFailed("VM did not report an IP address")+ }++ let ssh = SSHClient(host: ip, port: 22, user: adminUser, password: password)+ let result = try await ssh.execute(+ command: "csrutil status", timeout: try deadline.remaining(upTo: 30, operation: "SIP verification"))+ let statusOutput = result.output.trimmingCharacters(in: .whitespacesAndNewlines)+ let matches = result.exitCode == 0 && Self.statusMatches(statusOutput, expected: state)+ print(statusOutput)++ try await stopNormalBoot(+ child: child, controller: controller, deadline: deadline, operation: "verification")++ guard result.exitCode == 0 else {+ throw SipError.verificationFailed("csrutil status exited with status \(result.exitCode): \(statusOutput)")+ }+ guard matches else {+ throw SipError.verificationFailed("Unexpected csrutil status after \(state.rawValue): \(statusOutput)")+ }+ print("SIP is \(state == .off ? "disabled" : "enabled").")+ child.cleanup()+ } catch {+ await child.terminateAndWait()+ child.cleanup()+ throw error+ }+ }++ @MainActor private func waitForSSHReady(+ controller: LumeController, child: SipChildProcess, context: String, deadline: SipDeadline, maxSeconds: Double+ ) async throws -> VMDetails {+ let allowed = try deadline.remaining(upTo: maxSeconds, operation: context)+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))+ while ContinuousClock.now < localDeadline {+ try child.ensureRunning(context: context, redacting: [])+ if let details = try? controller.getDetails(name: name, storage: storage), details.status == "running",+ details.sshAvailable == true, let ip = details.ipAddress, !ip.isEmpty+ {+ return details+ }+ try await sleep(seconds: min(5, try deadline.remaining(upTo: 5, operation: context)))+ }+ throw SipError.verificationFailed(+ "VM never reached SSH-ready state during \(context). " + "Ensure Remote Login is enabled.")+ }++ @MainActor private func stopNormalBoot(+ child: SipChildProcess, controller: LumeController, deadline: SipDeadline, operation: String+ ) async throws {+ Logger.info("Stopping normal boot", metadata: ["operation": operation, "vm": name])+ await child.terminateAndWait()+ guard !child.isRunning else {+ throw SipError.childProcessTimedOut(+ context: "\(operation) stop", output: child.outputTail(redacting: []))+ }+ try await waitForStoppedState(controller: controller, deadline: deadline, operation: "\(operation) stop")+ }++ @MainActor private func waitForProcessExit(+ _ child: SipChildProcess, deadline: SipDeadline, maxSeconds: Double, context: String,+ redacting secrets: [String]+ ) async throws {+ let allowed = try deadline.remaining(upTo: maxSeconds, operation: context)+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))+ while child.isRunning && ContinuousClock.now < localDeadline { try await sleep(seconds: 1) }+ guard !child.isRunning else {+ throw SipError.childProcessTimedOut(context: context, output: child.outputTail(redacting: secrets))+ }+ guard child.terminationStatus == 0 else {+ throw SipError.childProcessExited(+ context: context, status: child.terminationStatus, output: child.outputTail(redacting: secrets))+ }+ }++ @MainActor private func waitForStoppedState(controller: LumeController, deadline: SipDeadline, operation: String)+ async throws+ {+ let allowed = try deadline.remaining(upTo: 30, operation: operation)+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))+ while ContinuousClock.now < localDeadline {+ if let details = try? controller.getDetails(name: name, storage: storage), details.status == "stopped" {+ return+ }+ try await sleep(seconds: 1)+ }+ throw SipError.vmDidNotStop(name, operation: operation)+ }++ @MainActor private func loadInitialDetails(controller: LumeController) throws -> VMDetails {+ do { return try controller.getDetails(name: name, storage: storage) } catch { throw SipError.vmNotFound(name) }+ }++ private func confirmChange() throws {+ let verb = state == .off ? "DISABLE" : "ENABLE"+ print("This will \(verb) System Integrity Protection on '\(name)'.")+ print("The VM will boot normally for credential validation, then into recovery.")+ print("Continue? [y/N]: ", terminator: "")+ let answer = readLine()?.trimmingCharacters(in: .whitespaces).lowercased() ?? ""+ guard answer == "y" || answer == "yes" else {+ print("Aborted.")+ throw ExitCode(1)+ }+ }++ private func resolvedAdminPassword() throws -> String {+ if adminPassword != nil && adminPasswordStdin { throw SipError.conflictingPasswordSources }+ let password: String+ if adminPasswordStdin {+ password = try readSecretLineFromStandardInput()+ } else {+ password = adminPassword ?? "lume"+ }+ guard !password.isEmpty else { throw SipError.emptyPassword }+ return password+ }++ private func readSecretLineFromStandardInput() throws -> String {+ let fd = STDIN_FILENO+ var original = termios()+ let isTerminal = isatty(fd) == 1+ var echoDisabled = false++ if isTerminal {+ guard tcgetattr(fd, &original) == 0 else {+ throw SipError.passwordTerminalConfigurationFailed+ }+ var noEcho = original+ noEcho.c_lflag &= ~tcflag_t(ECHO)+ guard tcsetattr(fd, TCSAFLUSH, &noEcho) == 0 else {+ throw SipError.passwordTerminalConfigurationFailed+ }+ echoDisabled = true+ FileHandle.standardError.write(Data("Admin password: ".utf8))+ }+ defer {+ if echoDisabled {+ var restored = original+ tcsetattr(fd, TCSAFLUSH, &restored)+ FileHandle.standardError.write(Data("\n".utf8))+ }+ }++ guard let password = readLine(strippingNewline: true) else { throw SipError.passwordStdinUnavailable }+ return password+ }++ private func resolvedSelfExecutable() -> String {+ let selfPath = ProcessInfo.processInfo.arguments[0]+ if selfPath.hasPrefix("/") { return selfPath }+ return which(selfPath) ?? selfPath+ }++ private func runArguments(recovery: Bool, vncPassword: String? = nil) -> [String] {+ var args = ["run", name, "--no-display"]+ if recovery { args.append(contentsOf: ["--recovery-mode", "true"]) }+ if let vncPassword { args.append(contentsOf: ["--vnc-port", "\(vncPort)", "--vnc-password", vncPassword]) }+ if let storage { args.append(contentsOf: ["--storage", storage]) }+ return args+ }++ private func sleep(seconds: Double) async throws { try await Task.sleep(for: .seconds(seconds)) }++ private func which(_ name: String) -> String? {+ let process = Process()+ process.executableURL = URL(fileURLWithPath: "/usr/bin/which")+ process.arguments = [name]+ let output = Pipe()+ process.standardOutput = output+ process.standardError = FileHandle.nullDevice+ try? process.run()+ process.waitUntilExit()+ guard process.terminationStatus == 0, let data = try? output.fileHandleForReading.readToEnd(),+ let path = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines),+ !path.isEmpty+ else { return nil }+ return path+ }++ static func validateInitialState(_ details: VMDetails, expectedName: String) throws {+ guard details.name == expectedName else { throw SipError.vmNotFound(expectedName) }+ guard details.os.lowercased() == "macos" else { throw SipError.unsupportedOS(details.os) }+ guard details.status == "stopped" else { throw SipError.vmNotStopped(expectedName, actual: details.status) }+ }++ static func requireVNCExecutable(_ path: String?) throws -> String {+ guard let path else { throw SipError.vncdoNotFound }+ return path+ }++ static func makeVNCPassword() -> String {+ // Classic VNC authentication uses only the first eight password bytes.+ let characters = Array("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")+ var generator = SystemRandomNumberGenerator()+ return String((0..<8).map { _ in+ characters[Int.random(in: characters.indices, using: &generator)]+ })+ }++ static func statusMatches(_ output: String, expected state: State) -> Bool {+ let prefix = "system integrity protection status:"+ guard let statusLine = output.split(whereSeparator: \.isNewline).map({+ $0.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()+ }).first(where: { $0.hasPrefix(prefix) }) else {+ return false+ }+ let value = statusLine.dropFirst(prefix.count).trimmingCharacters(in: .whitespaces)+ switch state {+ case .off: return value == "disabled" || value == "disabled."+ case .on: return value == "enabled" || value == "enabled."+ }+ }++ static func validateVNCPasswordCharacters(_ password: String) throws {+ let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789-")+ guard password.unicodeScalars.allSatisfy(allowed.contains) else { throw SipError.unsupportedPasswordCharacters }+ }+}++@MainActor struct SipRecoveryAutomator {+ typealias Sleeper = (Double) async throws -> Void+ typealias Timeout = (Double, String) throws -> Double++ private let sleeper: Sleeper++ init(sleeper: @escaping Sleeper = { seconds in try await Task.sleep(for: .seconds(seconds)) }) {+ self.sleeper = sleeper+ }++ func perform(+ driver: any RecoveryVNCDriving, state: Sip.State, adminUser: String, adminPassword: String,+ heartbeat: () throws -> Void,+ timeout: Timeout+ ) async throws {+ try await driver.waitForListening(deadlineSeconds: try timeout(60, "VNC startup"), heartbeat: heartbeat)+ try await driver.waitForFramebuffer(+ minSize: 15_000, deadlineSeconds: try timeout(90, "recovery picker"), label: "picker", heartbeat: heartbeat)++ try driver.key("right")+ try await pause(seconds: 1, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)+ try driver.key("right")+ try await pause(seconds: 1, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)+ try driver.snapshot("01-options-focused")+ try driver.key("enter")+ try await pause(seconds: 3, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)++ try await driver.waitForFramebuffer(+ minSize: 60_000, deadlineSeconds: try timeout(180, "recovery language selector"), label: "language",+ heartbeat: heartbeat)+ try driver.key("enter")+ try await pause(+ seconds: 45, operation: "recoveryOS main-menu transition", heartbeat: heartbeat, timeout: timeout)+ try driver.snapshot("02-recoveryOS-menu")++ try driver.click(x: 243, y: 14)+ try await pause(seconds: 1, operation: "Utilities menu", heartbeat: heartbeat, timeout: timeout)+ for _ in 0..<3 {+ try driver.key("down")+ try await pause(seconds: 0.2, operation: "Utilities menu", heartbeat: heartbeat, timeout: timeout)+ }+ try driver.snapshot("03-terminal-highlighted")+ try driver.key("enter")+ try await pause(seconds: 4, operation: "Terminal launch", heartbeat: heartbeat, timeout: timeout)+ try driver.snapshot("04-terminal-opened")++ try driver.type(state == .off ? "csrutil disable" : "csrutil enable")+ try driver.key("enter")+ try await pause(seconds: 3, operation: "csrutil prompt", heartbeat: heartbeat, timeout: timeout)+ try driver.snapshot("05-csrutil-prompt")++ let accountPrompt = "enter password for user \(adminUser):"+ let promptText = try await driver.waitForText(+ containing: ["[y/n]", accountPrompt],+ rejecting: ["no administrator was found", "failed to authenticate", "authentication failure"],+ deadlineSeconds: try timeout(15, "csrutil prompt"), label: "csrutil prompt", heartbeat: heartbeat)++ if !promptText.lowercased().contains(accountPrompt.lowercased()) {+ try driver.key("y")+ try driver.key("enter")+ try await pause(seconds: 3, operation: "csrutil password prompt", heartbeat: heartbeat, timeout: timeout)+ _ = try await driver.waitForText(+ containing: [accountPrompt],+ rejecting: ["no administrator was found", "failed to authenticate", "authentication failure"],+ deadlineSeconds: try timeout(15, "csrutil account prompt"), label: "csrutil account prompt",+ heartbeat: heartbeat)+ }+ try driver.snapshot("06-password-prompt")++ try driver.typeSensitive(adminPassword)+ try driver.key("enter")+ let expected = state == .off ? "system integrity protection is off." : "system integrity protection is on."+ _ = try await driver.waitForText(+ containing: [expected],+ rejecting: ["incorrect password", "authentication failed", "failed to modify", "try again"],+ deadlineSeconds: try timeout(20, "csrutil result"), label: "csrutil result", heartbeat: heartbeat)+ try driver.snapshot("07-after-password")++ try driver.type("sync; shutdown -h now")+ try driver.key("enter")+ try driver.snapshot("08-shutdown-sent")+ }++ private func pause(seconds: Double, operation: String, heartbeat: () throws -> Void, timeout: Timeout) async throws+ {+ var remaining = seconds+ while remaining > 0 {+ try heartbeat()+ let interval = min(1, remaining)+ let allowed = try timeout(interval, operation)+ try await sleeper(min(interval, allowed))+ remaining -= interval+ }+ try heartbeat()+ }+}++struct SipDeadline: Sendable {+ private let clock = ContinuousClock()+ private let end: ContinuousClock.Instant++ init(seconds: Int) { end = clock.now.advanced(by: .seconds(seconds)) }++ func remaining(upTo limit: Double, operation: String) throws -> Double {+ let duration = clock.now.duration(to: end).components+ let seconds = Double(duration.seconds) + Double(duration.attoseconds) / 1e18+ guard seconds > 0 else { throw SipError.timedOut(operation) }+ return min(limit, seconds)+ }+}++@MainActor final class SipChildProcess {+ private static let maximumTailBytes = 16 * 1024++ let process = Process()+ private let logURL: URL+ private let logHandle: FileHandle++ init(executable: String, arguments: [String], label: String) throws {+ let safeLabel = label.replacingOccurrences(of: " ", with: "-")+ logURL = FileManager.default.temporaryDirectory.appendingPathComponent(+ "lume-sip-\(safeLabel)-\(UUID().uuidString).log")+ guard FileManager.default.createFile(atPath: logURL.path, contents: nil, attributes: [.posixPermissions: 0o600])+ else { throw SipError.processSetupFailed("Could not create child-process log") }+ logHandle = try FileHandle(forWritingTo: logURL)+ process.executableURL = URL(fileURLWithPath: executable)+ process.arguments = arguments+ process.standardOutput = logHandle+ process.standardError = logHandle+ }++ var isRunning: Bool { process.isRunning }++ var terminationStatus: Int32 { process.isRunning ? -1 : process.terminationStatus }++ func start() throws { try process.run() }++ func ensureRunning(context: String, redacting secrets: [String]) throws {+ guard process.isRunning else {+ throw SipError.childProcessExited(+ context: context, status: terminationStatus, output: outputTail(redacting: secrets))+ }+ }++ func outputTail(redacting secrets: [String]) -> String {+ try? logHandle.synchronize()+ guard let data = try? Data(contentsOf: logURL) else { return "" }+ let tail = data.suffix(Self.maximumTailBytes)+ var output = String(decoding: tail, as: UTF8.self)+ for secret in secrets where !secret.isEmpty {+ output = output.replacingOccurrences(of: secret, with: "<redacted>")+ }+ return output.trimmingCharacters(in: .whitespacesAndNewlines)+ }++ func terminateAndWait() async {+ guard process.isRunning else { return }+ process.interrupt()+ await waitForTermination(seconds: 5)+ if process.isRunning {+ process.terminate()+ await waitForTermination(seconds: 5)+ }+ if process.isRunning {+ Darwin.kill(process.processIdentifier, SIGKILL)+ await waitForTermination(seconds: 2)+ }+ }++ func cleanup() {+ try? logHandle.close()+ try? FileManager.default.removeItem(at: logURL)+ }++ private func waitForTermination(seconds: Double) async {+ let deadline = ContinuousClock.now.advanced(by: .seconds(seconds))+ while process.isRunning && ContinuousClock.now < deadline { try? await Task.sleep(for: .milliseconds(100)) }+ }+}++enum SipError: Error, CustomStringConvertible {+ case vmNotFound(String)+ case vmNotStopped(String, actual: String)+ case vmDidNotStop(String, operation: String)+ case unsupportedOS(String)+ case vncdoNotFound+ case conflictingPasswordSources+ case passwordStdinUnavailable+ case passwordTerminalConfigurationFailed+ case emptyPassword+ case unsupportedPasswordCharacters+ case invalidTimeout(Int)+ case credentialPreflightFailed(String)+ case childProcessExited(context: String, status: Int32, output: String)+ case childProcessTimedOut(context: String, output: String)+ case processSetupFailed(String)+ case timedOut(String)+ case verificationFailed(String)++ var description: String {+ switch self {+ case .vmNotFound(let name): return "VM '\(name)' not found."+ case .vmNotStopped(let name, let actual): return "VM '\(name)' must be stopped (current status: \(actual))."+ case .vmDidNotStop(let name, let operation):+ return "VM '\(name)' did not reach stopped state after \(operation)."+ case .unsupportedOS(let os): return "The sip command supports macOS VMs only (found: \(os))."+ case .vncdoNotFound: return "vncdotool not found on PATH. Install with: pip3 install vncdotool"+ case .conflictingPasswordSources: return "Use either --admin-password or --admin-password-stdin, not both."+ case .passwordStdinUnavailable: return "Could not read the admin password from standard input."+ case .passwordTerminalConfigurationFailed:+ return "Could not disable terminal echo while reading the admin password."+ case .emptyPassword: return "The admin password cannot be empty."+ case .unsupportedPasswordCharacters:+ return "Recovery VNC currently supports admin passwords containing only "+ + "lowercase ASCII letters, digits, and hyphens."+ case .invalidTimeout(let timeout): return "Timeout must be greater than zero (received: \(timeout))."+ case .credentialPreflightFailed(let message): return "Admin credential preflight failed: \(message)"+ case .childProcessExited(let context, let status, let output):+ let suffix = output.isEmpty ? "" : "\n\(output)"+ return "The lume run child exited during \(context) with status \(status).\(suffix)"+ case .childProcessTimedOut(let context, let output):+ let suffix = output.isEmpty ? "" : "\n\(output)"+ return "Timed out waiting for the lume run child during \(context).\(suffix)"+ case .processSetupFailed(let message): return "Could not prepare the lume run child: \(message)"+ case .timedOut(let operation): return "The overall sip timeout expired during \(operation)."+ case .verificationFailed(let message): return "SIP verification failed: \(message)"+ }+ }+}diff --git a/libs/lume/src/FileSystem/Home.swift b/libs/lume/src/FileSystem/Home.swiftindex 8fd741e752..298f9ef65a 100644--- a/libs/lume/src/FileSystem/Home.swift+++ b/libs/lume/src/FileSystem/Home.swift@@ -222,7 +222,9 @@ final class Home {}}- /// Clones a VM directory using APFS clonefile for disk.img and regular copy for small files+ /// Clones a complete VM state using APFS clonefile for disk.img and regular copies for+ /// auxiliary files. macOS disk and auxiliary storage must remain paired because boot+ /// policy state spans both files./// - Parameters:/// - sourceName: Name of the source VM/// - destName: Name for the destination VMdiff --git a/libs/lume/src/SSH/SSHClient.swift b/libs/lume/src/SSH/SSHClient.swiftindex 46137e72b1..cb6b4b9daf 100644--- a/libs/lume/src/SSH/SSHClient.swift+++ b/libs/lume/src/SSH/SSHClient.swift@@ -46,6 +46,7 @@ public actor SSHClient {// Create a promise for the resultlet resultPromise = channel.eventLoop.makePromise(of: SSHResult.self)+ let resultState = CommandResultState(promise: resultPromise)// Create the SSH child channel for command execution.// We keep handler access + createChannel on the event loop to avoid@@ -58,7 +59,10 @@ public actor SSHClient {}return childChannel.eventLoop.makeCompletedFuture {- let execHandler = CommandExecHandler(command: command, resultPromise: resultPromise)+ let execHandler = CommandExecHandler(+ command: command,+ resultState: resultState+ )try childChannel.pipeline.syncOperations.addHandler(execHandler)}}@@ -70,24 +74,26 @@ public actor SSHClient {// Set up timeout if specifiedif timeout > 0 {let timeoutTask = channel.eventLoop.scheduleTask(in: .seconds(Int64(timeout))) {- resultPromise.fail(SSHError.timeout)+ resultState.fail(SSHError.timeout)childChannel.close(promise: nil)}// Cancel timeout when result is received- resultPromise.futureResult.whenComplete { _ in+ resultState.futureResult.whenComplete { _ intimeoutTask.cancel()}}- // Wait for command completion- let result = try await resultPromise.futureResult.get()-- // Clean up- try? await childChannel.closeFuture.get()- try? await channel.close().get()-- return result+ do {+ let result = try await resultState.futureResult.get()+ try? await childChannel.closeFuture.get()+ try? await channel.close().get()+ return result+ } catch {+ try? await childChannel.close().get()+ try? await channel.close().get()+ throw error+ }}/// Start an interactive SSH session@@ -222,6 +228,35 @@ private final class PasswordAuthDelegate: NIOSSHClientUserAuthenticationDelegate// MARK: - Command Execution Handler+private final class CommandResultState: @unchecked Sendable {+ private let promise: EventLoopPromise<SSHResult>+ private let completed = NIOLockedValueBox(false)++ init(promise: EventLoopPromise<SSHResult>) {+ self.promise = promise+ }++ var futureResult: EventLoopFuture<SSHResult> { promise.futureResult }++ func succeed(_ result: SSHResult) {+ guard claimCompletion() else { return }+ promise.succeed(result)+ }++ func fail(_ error: Error) {+ guard claimCompletion() else { return }+ promise.fail(error)+ }++ private func claimCompletion() -> Bool {+ completed.withLockedValue { completed in+ guard !completed else { return false }+ completed = true+ return true+ }+ }+}+/// Handles command execution on an SSH channel/// Note: @unchecked Sendable is safe because this handler is only used on a single event loopprivate final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendable {@@ -231,14 +266,14 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendabltypealias OutboundOut = SSHChannelDataprivate let command: String- private var resultPromise: EventLoopPromise<SSHResult>?+ private let resultState: CommandResultStateprivate var outputBuffer: ByteBufferprivate var exitStatus: Int32?private var channelClosed = false- init(command: String, resultPromise: EventLoopPromise<SSHResult>) {+ init(command: String, resultState: CommandResultState) {self.command = command- self.resultPromise = resultPromise+ self.resultState = resultStateself.outputBuffer = ByteBuffer()}@@ -291,7 +326,11 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendablfunc channelInactive(context: ChannelHandlerContext) {channelClosed = true- checkCompletion(context: context)+ if exitStatus == nil {+ failForMissingExitStatus()+ } else {+ checkCompletion(context: context)+ }}func errorCaught(context: ChannelHandlerContext, error: Error) {@@ -299,35 +338,34 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendabl}func handlerRemoved(context: ChannelHandlerContext) {- // If we haven't completed yet, complete with what we have- checkCompletion(context: context)+ if exitStatus == nil {+ failForMissingExitStatus()+ } else {+ checkCompletion(context: context)+ }}private func checkCompletion(context: ChannelHandlerContext) {- // Only complete if we have both exit status and channel is closed (or we have exit status)- guard let promise = resultPromise else { return }-- // Complete when we have exit status (some servers close channel before sending exit status)- if let status = exitStatus {- resultPromise = nil- let output = outputBuffer.readString(length: outputBuffer.readableBytes) ?? ""- promise.succeed(SSHResult(exitCode: status, output: output))- } else if channelClosed {- // Channel closed without exit status - assume success with exit code 0- resultPromise = nil+ if let status = exitStatus, channelClosed {let output = outputBuffer.readString(length: outputBuffer.readableBytes) ?? ""- promise.succeed(SSHResult(exitCode: 0, output: output))+ resultState.succeed(SSHResult(exitCode: status, output: output))}}+ private func failForMissingExitStatus() {+ resultState.fail(+ SSHError.commandFailed(+ exitCode: -1,+ message: "SSH channel closed without an exit status"+ )+ )+ }+private func failWithError(_ error: Error, context: ChannelHandlerContext) {- if let promise = resultPromise {- resultPromise = nil- if let sshError = error as? SSHError {- promise.fail(sshError)- } else {- promise.fail(SSHError.commandFailed(exitCode: -1, message: error.localizedDescription))- }+ if let sshError = error as? SSHError {+ resultState.fail(sshError)+ } else {+ resultState.fail(SSHError.commandFailed(exitCode: -1, message: String(describing: error)))}context.close(promise: nil)}diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swiftindex 164446fe8c..bfda9a518d 100644--- a/libs/lume/src/Utils/CommandDocExtractor.swift+++ b/libs/lume/src/Utils/CommandDocExtractor.swift@@ -56,6 +56,11 @@ struct CLIDocumentation: Codable {enum CommandDocExtractor {/// Extract documentation from all registered commandsstatic func extractAll() -> CLIDocumentation {+ let coverage = documentationCoverage+ precondition(+ coverage.missing.isEmpty && coverage.extra.isEmpty,+ "CLI documentation coverage mismatch. Missing: \(coverage.missing); extra: \(coverage.extra)"+ )return CLIDocumentation(name: "lume",version: Lume.Version.current,@@ -73,6 +78,7 @@ enum CommandDocExtractor {createDoc,pullDoc,pushDoc,+ convertDoc,imagesDoc,cloneDoc,getDoc,@@ -81,6 +87,7 @@ enum CommandDocExtractor {runDoc,stopDoc,sshDoc,+ sipDoc,ipswDoc,serveDoc,deleteDoc,@@ -90,9 +97,23 @@ enum CommandDocExtractor {checkUpdateDoc,updateDoc,setupDoc,+ dumpDocsDoc,]}+ static var documentationCoverage: (missing: [String], extra: [String]) {+ let registered = Swift.Set(CommandRegistry.allCommands.map(commandName))+ let documented = Swift.Set(allCommandDocs.map(\.name))+ return (+ missing: registered.subtracting(documented).sorted(),+ extra: documented.subtracting(registered).sorted()+ )+ }++ private static func commandName(_ command: ParsableCommand.Type) -> String {+ command.configuration.commandName ?? String(describing: command).lowercased()+ }+// MARK: - Createprivate static var createDoc: CommandDoc {@@ -171,6 +192,41 @@ enum CommandDocExtractor {)}+ // MARK: - Convert++ private static var convertDoc: CommandDoc {+ CommandDoc(+ name: "convert",+ abstract: "Convert a legacy Lume image to OCI-compliant format",+ discussion: nil,+ arguments: [+ ArgumentDoc(+ name: "source-image",+ help: "Source image to convert (legacy format, for example macos-tahoe:latest)",+ type: "String",+ isOptional: false+ ),+ ArgumentDoc(+ name: "target-image",+ help: "Target image to push in OCI format (name:tag)",+ type: "String",+ isOptional: false+ ),+ ],+ options: [+ OptionDoc(name: "additional-tags", shortName: nil, help: "Additional tags for the OCI image", type: "[String]", defaultValue: nil, isOptional: true),+ OptionDoc(name: "registry", shortName: nil, help: "Registry to pull from and push to", type: "String", defaultValue: "ghcr.io", isOptional: false),+ OptionDoc(name: "organization", shortName: nil, help: "Registry organization", type: "String", defaultValue: "trycua", isOptional: false),+ ],+ flags: [+ FlagDoc(name: "verbose", shortName: nil, help: "Enable verbose logging", defaultValue: false),+ FlagDoc(name: "dry-run", shortName: nil, help: "Prepare files without uploading", defaultValue: false),+ FlagDoc(name: "single-layer", shortName: nil, help: "Push one kubelet-compatible disk layer", defaultValue: false),+ ],+ subcommands: []+ )+ }+// MARK: - Imagesprivate static var imagesDoc: CommandDoc {@@ -332,6 +388,33 @@ enum CommandDocExtractor {)}+ // MARK: - SIP++ private static var sipDoc: CommandDoc {+ CommandDoc(+ name: "sip",+ abstract: "Enable or disable System Integrity Protection on a macOS VM",+ discussion: "Validates the administrator account, changes SIP from paired Recovery over VNC, and verifies the canonical csrutil status after a normal boot.",+ arguments: [+ ArgumentDoc(name: "state", help: "Desired SIP state: on or off", type: "String", isOptional: false),+ ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),+ ],+ options: [+ OptionDoc(name: "admin-user", shortName: nil, help: "Administrator username in the guest", type: "String", defaultValue: "lume", isOptional: false),+ OptionDoc(name: "admin-password", shortName: nil, help: "Administrator password in the guest; prefer --admin-password-stdin", type: "String", defaultValue: nil, isOptional: true),+ OptionDoc(name: "screenshot-dir", shortName: nil, help: "Directory for Recovery framebuffer screenshots", type: "String", defaultValue: nil, isOptional: true),+ OptionDoc(name: "vnc-port", shortName: nil, help: "Port for the temporary Recovery VNC server", type: "Int", defaultValue: "5999", isOptional: false),+ OptionDoc(name: "storage", shortName: nil, help: "VM storage location", type: "String", defaultValue: nil, isOptional: true),+ OptionDoc(name: "timeout", shortName: nil, help: "Overall timeout in seconds", type: "Int", defaultValue: "900", isOptional: false),+ ],+ flags: [+ FlagDoc(name: "yes", shortName: "y", help: "Skip the interactive confirmation prompt", defaultValue: false),+ FlagDoc(name: "admin-password-stdin", shortName: nil, help: "Read one administrator-password line from standard input without echo", defaultValue: false),+ ],+ subcommands: []+ )+ }+// MARK: - IPSWprivate static var ipswDoc: CommandDoc {@@ -566,4 +649,22 @@ enum CommandDocExtractor {subcommands: [])}++ // MARK: - Dump Docs++ private static var dumpDocsDoc: CommandDoc {+ CommandDoc(+ name: "dump-docs",+ abstract: "Output CLI and API documentation as JSON for tooling and integrations",+ discussion: nil,+ arguments: [],+ options: [+ OptionDoc(name: "type", shortName: nil, help: "Documentation type: cli, api, or all", type: "String", defaultValue: "cli", isOptional: false),+ ],+ flags: [+ FlagDoc(name: "pretty", shortName: nil, help: "Pretty-print JSON output", defaultValue: false),+ ],+ subcommands: []+ )+ }}diff --git a/libs/lume/src/Utils/CommandRegistry.swift b/libs/lume/src/Utils/CommandRegistry.swiftindex 4752567640..a9b77b1e28 100644--- a/libs/lume/src/Utils/CommandRegistry.swift+++ b/libs/lume/src/Utils/CommandRegistry.swift@@ -15,6 +15,7 @@ enum CommandRegistry {Run.self,Stop.self,SSH.self,+ Sip.self,IPSW.self,Serve.self,Delete.self,diff --git a/libs/lume/src/Utils/VNCDriver.swift b/libs/lume/src/Utils/VNCDriver.swiftnew file mode 100644index 0000000000..48349abc53--- /dev/null+++ b/libs/lume/src/Utils/VNCDriver.swift@@ -0,0 +1,309 @@+import Darwin+import Foundation+import Vision++@MainActor protocol RecoveryVNCDriving {+ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void) async throws+ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void)+ async throws+ func waitForText(+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,+ label: String, heartbeat: () throws -> Void+ ) async throws -> String+ func type(_ text: String) throws+ func typeSensitive(_ text: String) throws+ func key(_ name: String) throws+ func click(x: Int, y: Int) throws+ func snapshot(_ tag: String) throws+}++/// Thin wrapper around the `vncdotool` CLI (`pip3 install vncdotool`).+///+/// Used only by `lume sip` to drive the recoveryOS UI. The tool is invoked+/// per action via `Process`, and all args go through argv (never a shell).+///+/// Known limitations of vncdotool against macOS VNC servers:+/// - `type` doesn't shift correctly: uppercase, `_`, `&`, etc. get+/// corrupted. Only send unshifted characters through `type`.+/// - Cmd-key chords (⇧⌘T etc.) do NOT reliably route through VZ's VNC+/// server. Use menu-bar clicks + arrow-key navigation instead.+///+/// A future commit can swap this for a native Swift RFB client without+/// changing call sites. The in-tree `VNCClient` actor is a candidate, but+/// has an outstanding NWConnection stall when invoked from certain+/// `@MainActor` call chains that needs investigation before use here.+@MainActor struct VNCDriver: RecoveryVNCDriving {+ let vncdo: String+ let host: String+ let port: Int+ let password: String+ let screenshotDir: String?++ private var target: String { "\(host)::\(port)" }++ /// Find `vncdo` (or `vncdotool`) on PATH. Also checks the pip3+ /// user-scripts directory (`~/Library/Python/<ver>/bin`) since+ /// `pip3 install --user vncdotool` puts it there and that's often not+ /// on PATH by default.+ static func locateVncdo() -> String? {+ for name in ["vncdo", "vncdotool"] { if let hit = whichPath(name) { return hit } }+ let home = NSHomeDirectory()+ let pythonBase = "\(home)/Library/Python"+ if let dirs = try? FileManager.default.contentsOfDirectory(atPath: pythonBase) {+ for dir in dirs {+ for name in ["vncdo", "vncdotool"] {+ let candidate = "\(pythonBase)/\(dir)/bin/\(name)"+ if FileManager.default.isExecutableFile(atPath: candidate) { return candidate }+ }+ }+ }+ return nil+ }++ private static func whichPath(_ name: String) -> String? {+ let p = Process()+ p.executableURL = URL(fileURLWithPath: "/usr/bin/which")+ p.arguments = [name]+ let out = Pipe()+ p.standardOutput = out+ p.standardError = Pipe()+ try? p.run()+ p.waitUntilExit()+ guard p.terminationStatus == 0, let data = try? out.fileHandleForReading.readToEnd(),+ let str = String(data: data, encoding: .utf8)+ else { return nil }+ let trimmed = str.trimmingCharacters(in: .whitespacesAndNewlines)+ return trimmed.isEmpty ? nil : trimmed+ }++ // MARK: - Public API++ /// Wait until the VNC server is accepting TCP connections.+ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void = {}) async throws {+ let deadline = Date().addingTimeInterval(deadlineSeconds)+ while Date() < deadline {+ try heartbeat()+ if canConnect() { return }+ try await sleep(seconds: 1)+ }+ throw VNCDriverError.timeout("VNC server never became reachable on \(target)")+ }++ /// Poll `capture` until the returned PNG exceeds `minSize` bytes — a+ /// heuristic that reliably distinguishes "framebuffer still black / boot+ /// splash" from "actual UI rendered."+ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void = {})+ async throws+ {+ let deadline = Date().addingTimeInterval(deadlineSeconds)+ let tempPath = "/tmp/lume-sip-fb-\(UUID().uuidString.prefix(8)).png"+ defer { try? FileManager.default.removeItem(atPath: tempPath) }+ var lastSize = 0+ var lastError: Error?+ while Date() < deadline {+ try heartbeat()+ do {+ try run(["capture", tempPath])+ lastError = nil+ } catch { lastError = error }+ let attrs = try? FileManager.default.attributesOfItem(atPath: tempPath)+ let size = (attrs?[.size] as? NSNumber)?.intValue ?? 0+ lastSize = size+ if size >= minSize {+ Logger.info("Framebuffer ready", metadata: ["label": label, "png_bytes": "\(size)"])+ return+ }+ try await sleep(seconds: 4)+ }+ let errorSuffix = lastError.map { "; last capture error: \($0)" } ?? ""+ throw VNCDriverError.timeout(+ "Framebuffer for '\(label)' never reached \(minSize) bytes " + "(last: \(lastSize))\(errorSuffix)")+ }++ /// Poll screenshots until OCR finds an expected terminal result. Failure+ /// phrases abort immediately so a bad password is reported before the+ /// workflow accidentally types the shutdown command into another prompt.+ func waitForText(+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,+ label: String, heartbeat: () throws -> Void = {}+ ) async throws -> String {+ let deadline = Date().addingTimeInterval(deadlineSeconds)+ let tempPath = "/tmp/lume-sip-ocr-\(UUID().uuidString.prefix(8)).png"+ defer { try? FileManager.default.removeItem(atPath: tempPath) }+ let expected = expectedPhrases.map(Self.normalizeText)+ let failures = failurePhrases.map(Self.normalizeText)+ var lastText = ""+ var lastError: Error?++ while Date() < deadline {+ try heartbeat()+ do {+ try run(["capture", tempPath])+ lastText = try Self.recognizeText(at: tempPath)+ lastError = nil+ let normalized = Self.normalizeText(lastText)++ if let phrase = failures.first(where: normalized.contains) {+ throw VNCDriverError.unexpectedText("Framebuffer for '\(label)' contained failure text '\(phrase)'")+ }+ if expected.contains(where: normalized.contains) { return lastText }+ } catch let error as VNCDriverError {+ if case .unexpectedText = error { throw error }+ lastError = error+ } catch { lastError = error }+ try await sleep(seconds: 2)+ }++ let recognized = Self.normalizeText(lastText)+ let textSuffix = recognized.isEmpty ? "" : "; last OCR text: \(recognized)"+ let errorSuffix = lastError.map { "; last OCR error: \($0)" } ?? ""+ throw VNCDriverError.timeout(+ "Framebuffer for '\(label)' did not contain expected text" + "\(textSuffix)\(errorSuffix)")+ }++ /// Type a plain string. Unshifted characters only — see the type doc.+ func type(_ text: String) throws { try run(["type", text]) }++ /// Type a secret without putting it in the vncdotool process arguments.+ /// `typefile -` reads the value from the child process's standard input.+ func typeSensitive(_ text: String) throws {+ guard let data = text.data(using: .utf8) else { throw VNCDriverError.invalidSensitiveText }+ try run(["typefile", "-"], standardInput: data)+ }++ /// Send a single named key (e.g. `enter`, `right`, `y`).+ func key(_ name: String) throws { try run(["key", name]) }++ /// Send a keyboard chord. `modifiers` come from vncdotool's named-key+ /// vocabulary (`shift`, `ctrl`, `alt`, `super`/`cmd`).+ /// NOTE: VZ's VNC server does not reliably route Cmd chords; prefer+ /// menu-bar clicks + arrow navigation for menu shortcuts.+ func chord(modifiers: [String], key: String) throws {+ let chord = (modifiers + [key]).joined(separator: "-")+ try run(["key", chord])+ }++ /// Move the pointer to (x, y) and left-click.+ func click(x: Int, y: Int) throws { try run(["move", "\(x)", "\(y)", "click", "1"]) }++ /// Snapshot the current framebuffer to the screenshot dir if configured.+ /// Silent no-op when the dir isn't set.+ func snapshot(_ tag: String) throws {+ guard let dir = screenshotDir else { return }+ try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)+ let path = "\(dir)/\(tag).png"+ try run(["capture", path])+ }++ // MARK: - Internals++ private func canConnect() -> Bool {+ let host = CFHostCreateWithName(nil, self.host as CFString).takeRetainedValue()+ var readStream: Unmanaged<CFReadStream>?+ var writeStream: Unmanaged<CFWriteStream>?+ CFStreamCreatePairWithSocketToCFHost(nil, host, Int32(port), &readStream, &writeStream)+ defer {+ readStream?.release()+ writeStream?.release()+ }+ guard let r = readStream?.takeUnretainedValue() else { return false }+ let ok = CFReadStreamOpen(r)+ if ok { CFReadStreamClose(r) }+ return ok+ }++ private func run(_ args: [String], standardInput: Data? = nil) throws {+ let outputURL = FileManager.default.temporaryDirectory.appendingPathComponent(+ "lume-vncdo-\(UUID().uuidString).log"+ )+ guard FileManager.default.createFile(+ atPath: outputURL.path,+ contents: nil,+ attributes: [.posixPermissions: 0o600]+ ) else {+ throw VNCDriverError.outputCaptureFailed+ }+ let outputHandle: FileHandle+ do {+ outputHandle = try FileHandle(forWritingTo: outputURL)+ } catch {+ try? FileManager.default.removeItem(at: outputURL)+ throw VNCDriverError.outputCaptureFailed+ }+ defer {+ try? outputHandle.close()+ try? FileManager.default.removeItem(at: outputURL)+ }++ let p = Process()+ p.executableURL = URL(fileURLWithPath: vncdo)+ p.arguments = ["-s", target, "-p", password, "-t", "30"] + args+ p.standardOutput = outputHandle+ p.standardError = outputHandle+ let input = standardInput.map { _ in Pipe() }+ p.standardInput = input+ try p.run()+ if let standardInput, let input {+ input.fileHandleForWriting.write(standardInput)+ try? input.fileHandleForWriting.close()+ }++ let deadline = Date().addingTimeInterval(35)+ while p.isRunning && Date() < deadline {+ Thread.sleep(forTimeInterval: 0.05)+ }+ if p.isRunning {+ p.terminate()+ Thread.sleep(forTimeInterval: 0.2)+ if p.isRunning {+ Darwin.kill(p.processIdentifier, SIGKILL)+ }+ p.waitUntilExit()+ throw VNCDriverError.timeout("vncdotool command exceeded 35 seconds")+ }++ try? outputHandle.synchronize()+ let outputData = (try? Data(contentsOf: outputURL)) ?? Data()+ let outputText =+ String(data: outputData, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""+ if p.terminationStatus != 0 { throw VNCDriverError.commandFailed(args, p.terminationStatus, outputText) }+ }++ private static func recognizeText(at path: String) throws -> String {+ let request = VNRecognizeTextRequest()+ request.recognitionLevel = .accurate+ request.usesLanguageCorrection = false+ request.recognitionLanguages = ["en-US"]+ let handler = VNImageRequestHandler(url: URL(fileURLWithPath: path))+ try handler.perform([request])+ return (request.results ?? []).compactMap { $0.topCandidates(1).first?.string }.joined(separator: "\n")+ }++ private static func normalizeText(_ text: String) -> String {+ text.lowercased().split(whereSeparator: { $0.isWhitespace }).joined(separator: " ")+ }++ private func sleep(seconds: Double) async throws {+ try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))+ }+}++enum VNCDriverError: Error, CustomStringConvertible {+ case timeout(String)+ case commandFailed([String], Int32, String)+ case unexpectedText(String)+ case invalidSensitiveText+ case outputCaptureFailed++ var description: String {+ switch self {+ case .timeout(let msg): return "VNC driver timeout: \(msg)"+ case .commandFailed(let args, let code, let output):+ let suffix = output.isEmpty ? "" : ": \(output)"+ return "vncdotool \(args.joined(separator: " ")) exited with \(code)\(suffix)"+ case .unexpectedText(let msg): return "VNC terminal check failed: \(msg)"+ case .invalidSensitiveText: return "The sensitive VNC input could not be encoded as UTF-8"+ case .outputCaptureFailed: return "Could not create a private vncdotool output log"+ }+ }+}diff --git a/libs/lume/src/Virtualization/VMVirtualizationService.swift b/libs/lume/src/Virtualization/VMVirtualizationService.swiftindex cf00bc4d70..b4560c4b0a 100644--- a/libs/lume/src/Virtualization/VMVirtualizationService.swift+++ b/libs/lume/src/Virtualization/VMVirtualizationService.swift@@ -326,6 +326,43 @@ final class DarwinVirtualizationService: BaseVirtualizationService {spiceAgentConsoleDevice.ports[0] = spiceAgentPortvzConfig.consoleDevices.append(spiceAgentConsoleDevice)+ // Optional serial console for debugging. When LUME_SERIAL_CONSOLE points+ // at a writable path, attach a virtio serial port whose output is written+ // there. Useful for observing early boot / recoveryOS behaviour that has+ // no other headless channel.+ if let serialLogPath = ProcessInfo.processInfo.environment["LUME_SERIAL_CONSOLE"],+ !serialLogPath.isEmpty+ {+ if !FileManager.default.fileExists(atPath: serialLogPath) {+ FileManager.default.createFile(atPath: serialLogPath, contents: nil)+ }+ if let writeHandle = FileHandle(forWritingAtPath: serialLogPath) {+ writeHandle.seekToEndOfFile()+ let serialAttachment = VZFileHandleSerialPortAttachment(+ fileHandleForReading: nil,+ fileHandleForWriting: writeHandle+ )+ // 1) Classic virtio serial port.+ let serialPort = VZVirtioConsoleDeviceSerialPortConfiguration()+ serialPort.attachment = serialAttachment+ vzConfig.serialPorts = [serialPort]+ // 2) A virtio console port marked isConsole, which designates it+ // as the system console — some guests route console output here.+ let consoleDevice = VZVirtioConsoleDeviceConfiguration()+ let consolePort = VZVirtioConsolePortConfiguration()+ consolePort.isConsole = true+ consolePort.name = "lume.console"+ consolePort.attachment = serialAttachment+ consoleDevice.ports[0] = consolePort+ vzConfig.consoleDevices.append(consoleDevice)+ Logger.info("Attached serial console", metadata: ["path": serialLogPath])+ } else {+ Logger.error(+ "Failed to open serial console log for writing",+ metadata: ["path": serialLogPath])+ }+ }+// Directory sharinglet directorySharingDevices = createDirectorySharingDevices(sharedDirectories: config.sharedDirectories)diff --git a/libs/lume/tests/CommandDocExtractorTests.swift b/libs/lume/tests/CommandDocExtractorTests.swiftnew file mode 100644index 0000000000..f91aaafba7--- /dev/null+++ b/libs/lume/tests/CommandDocExtractorTests.swift@@ -0,0 +1,12 @@+import Testing++@testable import lume++@Test("CLI reference covers every registered command")+func commandDocumentationCoversRegistry() {+ let coverage = CommandDocExtractor.documentationCoverage++ #expect(coverage.missing.isEmpty)+ #expect(coverage.extra.isEmpty)+ #expect(CommandDocExtractor.extractAll().commands.contains { $0.name == "sip" })+}diff --git a/libs/lume/tests/LumeControllerTests.swift b/libs/lume/tests/LumeControllerTests.swiftindex a21548dace..9550bd64c3 100644--- a/libs/lume/tests/LumeControllerTests.swift+++ b/libs/lume/tests/LumeControllerTests.swift@@ -34,6 +34,20 @@ private final class FailingVMFactory: VMFactory {}}+@MainActor+private final class TestVMFactory: VMFactory {+ func createVM(+ vmDirContext: VMDirContext,+ imageLoader: ImageLoader?+ ) throws -> VM {+ MockVM(+ vmDirContext: vmDirContext,+ virtualizationServiceFactory: { _ in MockVMVirtualizationService() },+ vncServiceFactory: { MockVNCService(vmDirectory: $0) }+ )+ }+}+@MainActor@Test("create cleans up pre-created VM directory when setup fails")func testCreateCleansUpPrecreatedDirectoryOnFailure() async throws {@@ -87,6 +101,68 @@ func testCreateCleansUpPrecreatedDirectoryOnFailure() async throws {#expect(!orphanVMDir.exists())}+@MainActor+@Test("clone preserves paired disk and auxiliary storage")+func testClonePreservesPairedBootPolicyState() throws {+ let tempConfigDir = try createTempDirectory()+ let tempHomeDir = try createTempDirectory()++ defer {+ try? FileManager.default.removeItem(at: tempConfigDir)+ try? FileManager.default.removeItem(at: tempHomeDir)+ }++ let previousXDGConfigHome = ProcessInfo.processInfo.environment["XDG_CONFIG_HOME"]+ setenv("XDG_CONFIG_HOME", tempConfigDir.path, 1)+ defer {+ if let previousXDGConfigHome {+ setenv("XDG_CONFIG_HOME", previousXDGConfigHome, 1)+ } else {+ unsetenv("XDG_CONFIG_HOME")+ }+ }++ let settingsManager = SettingsManager(fileManager: .default)+ try settingsManager.setHomeDirectory(path: tempHomeDir.path)+ let home = Home(settingsManager: settingsManager, fileManager: .default)+ let controller = LumeController(home: home, vmFactory: TestVMFactory())++ let sourceDir = try home.getVMDirectory("sip-off-seed")+ try FileManager.default.createDirectory(+ at: sourceDir.dir.url,+ withIntermediateDirectories: true+ )++ let diskData = Data(repeating: 0xA5, count: 1024 * 1024)+ let nvramData = Data((0..<4096).map { UInt8($0 % 251) })+ try diskData.write(to: sourceDir.diskPath.url)+ try nvramData.write(to: sourceDir.nvramPath.url)++ let sourceMachineIdentifier = Data(repeating: 0x11, count: 32)+ let sourceMacAddress = "02:00:00:00:00:01"+ let sourceConfig = try VMConfig(+ os: "macOS",+ cpuCount: 4,+ memorySize: 8 * 1024 * 1024 * 1024,+ diskSize: UInt64(diskData.count),+ macAddress: sourceMacAddress,+ display: "1024x768",+ hardwareModel: Data(repeating: 0x22, count: 32),+ machineIdentifier: sourceMachineIdentifier+ )+ try sourceDir.saveConfig(sourceConfig)++ try controller.clone(name: "sip-off-seed", newName: "worker-001")++ let cloneDir = try home.getVMDirectory("worker-001")+ let cloneConfig = try cloneDir.loadConfig()++ #expect(try Data(contentsOf: cloneDir.diskPath.url) == diskData)+ #expect(try Data(contentsOf: cloneDir.nvramPath.url) == nvramData)+ #expect(cloneConfig.machineIdentifier != sourceMachineIdentifier)+ #expect(cloneConfig.macAddress != sourceMacAddress)+}+private func createTempDirectory() throws -> URL {let tempDir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)diff --git a/libs/lume/tests/SipTests.swift b/libs/lume/tests/SipTests.swiftnew file mode 100644index 0000000000..aad4ef8f46--- /dev/null+++ b/libs/lume/tests/SipTests.swift@@ -0,0 +1,166 @@+import Foundation+import Testing++@testable import lume++@MainActor private final class MockRecoveryVNCDriver: RecoveryVNCDriving {+ var events: [String] = []+ var receivedSensitiveInput = false+ var usesDirectAccountPrompt = false++ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void) async throws {+ try heartbeat()+ events.append("listening")+ }++ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void)+ async throws+ {+ try heartbeat()+ events.append("framebuffer:\(label)")+ }++ func waitForText(+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,+ label: String, heartbeat: () throws -> Void+ ) async throws -> String {+ try heartbeat()+ let text: String+ if label == "csrutil prompt" {+ text = usesDirectAccountPrompt ? expectedPhrases.last ?? "" : "[y/n]"+ } else {+ text = expectedPhrases.first ?? ""+ }+ events.append("text:\(text)")+ return text+ }++ func type(_ text: String) throws { events.append("type:\(text)") }++ func typeSensitive(_ text: String) throws {+ receivedSensitiveInput = !text.isEmpty+ events.append("sensitive-input")+ }++ func key(_ name: String) throws { events.append("key:\(name)") }++ func click(x: Int, y: Int) throws { events.append("click:\(x),\(y)") }++ func snapshot(_ tag: String) throws { events.append("snapshot:\(tag)") }+}++@MainActor @Test("sip parses stdin credentials and the short confirmation flag") func sipCommandParsing() throws {+ let root = try Lume.parseAsRoot(["sip", "off", "test-vm", "-y", "--admin-password-stdin"])+ let command = try #require(root as? Sip)++ #expect(command.state == .off)+ #expect(command.name == "test-vm")+ #expect(command.yes)+ #expect(command.adminPasswordStdin)+}++@Test("sip validates VM state and target status") func sipValidation() throws {+ let stoppedMac = vmDetails(os: "macOS", status: "stopped")+ try Sip.validateInitialState(stoppedMac, expectedName: "test-vm")+ #expect(Sip.statusMatches("System Integrity Protection status: disabled.", expected: .off))+ #expect(Sip.statusMatches("System Integrity Protection status: enabled.", expected: .on))+ #expect(!Sip.statusMatches("System Integrity Protection status: enabled.", expected: .off))+ let customized = """+ System Integrity Protection status: enabled (Custom Configuration).+ Filesystem Protections: disabled+ Debugging Restrictions: enabled+ """+ #expect(!Sip.statusMatches(customized, expected: .off))+ #expect(!Sip.statusMatches(customized, expected: .on))++ #expect(throws: SipError.self) {+ try Sip.validateInitialState(vmDetails(os: "linux", status: "stopped"), expectedName: "test-vm")+ }+ #expect(throws: SipError.self) {+ try Sip.validateInitialState(vmDetails(os: "macOS", status: "running"), expectedName: "test-vm")+ }+ #expect(throws: SipError.self) { try Sip.requireVNCExecutable(nil) }+ #expect(throws: SipError.self) { try Sip.validateVNCPasswordCharacters("Uppercase") }++ let vncPasswords = Swift.Set<String>((0..<8).map { _ in Sip.makeVNCPassword() })+ #expect(vncPasswords.allSatisfy { $0.utf8.count == 8 })+ #expect(vncPasswords.count > 1)+}++@MainActor @Test("recovery automation enters the requested csrutil command and verifies its result")+func sipRecoveryAutomation() async throws {+ for state in [Sip.State.off, .on] {+ let driver = MockRecoveryVNCDriver()+ driver.usesDirectAccountPrompt = state == .on+ var heartbeats = 0+ let automator = SipRecoveryAutomator(sleeper: { _ in })++ try await automator.perform(+ driver: driver, state: state, adminUser: "lume", adminPassword: "secret", heartbeat: { heartbeats += 1 },+ timeout: { limit, _ in limit })++ let verb = state == .off ? "disable" : "enable"+ let result = state == .off ? "off" : "on"+ #expect(driver.events.contains("type:csrutil \(verb)"))+ #expect(driver.events.contains("text:enter password for user lume:"))+ #expect(driver.events.contains("key:y") == (state == .off))+ #expect(driver.events.contains("text:system integrity protection is \(result)."))+ #expect(driver.events.contains("sensitive-input"))+ #expect(driver.receivedSensitiveInput)+ #expect(driver.events.suffix(3).contains("type:sync; shutdown -h now"))+ #expect(heartbeats > 0)+ }+}++@MainActor @Test("sensitive VNC input is sent on stdin and never in argv") func vncSensitiveInputUsesStdin() throws {+ let directory = FileManager.default.temporaryDirectory.appendingPathComponent(+ "lume-sip-vnc-test-\(UUID().uuidString)")+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: directory) }++ let executable = directory.appendingPathComponent("vncdo")+ let argumentsLog = directory.appendingPathComponent("arguments")+ let stdinLog = directory.appendingPathComponent("stdin")+ let script = """+ #!/bin/sh+ printf '%s\\n' "$@" > '\(argumentsLog.path)'+ head -c 262144 /dev/zero+ cat > '\(stdinLog.path)'+ """+ try script.write(to: executable, atomically: true, encoding: .utf8)+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: executable.path)++ let secret = "sentinel-secret"+ let driver = VNCDriver(+ vncdo: executable.path, host: "127.0.0.1", port: 5999, password: "transient-vnc-password", screenshotDir: nil)+ try driver.typeSensitive(secret)++ let arguments = try String(contentsOf: argumentsLog, encoding: .utf8)+ let standardInput = try String(contentsOf: stdinLog, encoding: .utf8)+ #expect(!arguments.contains(secret))+ #expect(arguments.contains("typefile\n-"))+ #expect(standardInput == secret)+}++@MainActor @Test("lume child output cannot fill an undrained pipe") func sipChildProcessHandlesLargeOutput()+ async throws+{+ let child = try SipChildProcess(+ executable: "/bin/sh", arguments: ["-c", "yes output | head -c 262144"], label: "large-output-test")+ defer { child.cleanup() }++ try child.start()+ for _ in 0..<100 where child.isRunning { try await Task.sleep(for: .milliseconds(20)) }+ if child.isRunning { await child.terminateAndWait() }++ #expect(!child.isRunning)+ #expect(child.terminationStatus == 0)+ #expect(!child.outputTail(redacting: []).isEmpty)+}++private func vmDetails(os: String, status: String) -> VMDetails {+ VMDetails(+ name: "test-vm", os: os, cpuCount: 4, memorySize: 8 * 1024 * 1024 * 1024,+ diskSize: DiskSize(allocated: 1, total: 2), display: "1024x768", status: status, vncUrl: nil, ipAddress: nil,+ locationName: "home")+}diff --git a/scripts/docs-generators/lume.ts b/scripts/docs-generators/lume.tsindex 6142a1b3cd..cd56aafc2d 100644--- a/scripts/docs-generators/lume.ts+++ b/scripts/docs-generators/lume.ts@@ -323,41 +323,44 @@ export function generateCLIReferenceMDX(docs: CLIDocumentation): string {lines.push('For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).');lines.push('');- // Group commands by category- const vmManagement = ['create', 'run', 'stop', 'delete', 'clone'];- const vmInfo = ['ls', 'get', 'set'];- const imageManagement = ['images', 'pull', 'push', 'ipsw', 'prune'];- const guestAccess = ['ssh', 'setup'];- const configuration = ['config', 'serve', 'logs', 'check-update', 'update'];-- lines.push('## VM Management');- lines.push('');- for (const cmd of docs.commands.filter((c) => vmManagement.includes(c.name))) {- lines.push(...generateCommandDoc(cmd, '###'));- }-- lines.push('## VM Information and Configuration');- lines.push('');- for (const cmd of docs.commands.filter((c) => vmInfo.includes(c.name))) {- lines.push(...generateCommandDoc(cmd, '###'));- }-- lines.push('## Image Management');- lines.push('');- for (const cmd of docs.commands.filter((c) => imageManagement.includes(c.name))) {- lines.push(...generateCommandDoc(cmd, '###'));- }+ const groups = [+ { title: 'VM Management', commands: ['create', 'run', 'stop', 'delete', 'clone'] },+ { title: 'VM Information and Configuration', commands: ['ls', 'get', 'set'] },+ {+ title: 'Image Management',+ commands: ['images', 'pull', 'push', 'convert', 'ipsw', 'prune'],+ },+ { title: 'Guest Access and Security', commands: ['ssh', 'setup', 'sip'] },+ {+ title: 'Configuration and Server',+ commands: ['config', 'serve', 'logs', 'check-update', 'update'],+ },+ { title: 'Developer Tools', commands: ['dump-docs'] },+ ];- lines.push('## Guest Access and Setup');- lines.push('');- for (const cmd of docs.commands.filter((c) => guestAccess.includes(c.name))) {- lines.push(...generateCommandDoc(cmd, '###'));+ const assignedCommands = groups.flatMap((group) => group.commands);+ const duplicateAssignments = assignedCommands.filter(+ (name, index) => assignedCommands.indexOf(name) !== index+ );+ const ungroupedCommands = docs.commands+ .map((command) => command.name)+ .filter((name) => !assignedCommands.includes(name));++ if (duplicateAssignments.length > 0 || ungroupedCommands.length > 0) {+ throw new Error(+ `CLI command grouping mismatch. Ungrouped: ${[...new Set(ungroupedCommands)].sort().join(', ') || 'none'}; duplicated: ${[...new Set(duplicateAssignments)].sort().join(', ') || 'none'}`+ );}- lines.push('## Configuration and Server');- lines.push('');- for (const cmd of docs.commands.filter((c) => configuration.includes(c.name))) {- lines.push(...generateCommandDoc(cmd, '###'));+ for (const group of groups) {+ lines.push(`## ${group.title}`);+ lines.push('');+ for (const commandName of group.commands) {+ const command = docs.commands.find((candidate) => candidate.name === commandName);+ if (command) {+ lines.push(...generateCommandDoc(command, '###'));+ }+ }}// Global options