Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Foundation
import IcliKit
import IcliSystem
import VphonedNative
// MARK: - Developer Mode Snapshot
/// The Developer Mode status `device.info` reports, read off the request path.
/// amfid answers the status request at once on an iPhone, but not on the tvOS
/// 26.6 and HomePod 27.0 guests checked (2026-11-03), where each query waits
/// its full 10 s (`icli_amfi_developer_mode_json`); `device.info` paid that on
/// every call, 10.03 s instead of 0.03 s.
/// The status is read once at startup and again in the background when it is
/// older than ``maximumAge``, one query at a time; `device.info` returns the
/// last answer, empty until there is one or when amfid never answers.
/// `developer_mode.status` still asks amfid directly.
final class GuestDeveloperModeSnapshot: @unchecked Sendable {
static let shared = GuestDeveloperModeSnapshot()
static let maximumAge: TimeInterval = 30
private let lock = NSLock()
private var status: [String: Any] = [:]
private var readAt: Date?
private var reading = false
func startOnStartup() {
refreshIfStale()
}
func current() -> [String: Any] {
refreshIfStale()
lock.lock()
defer { lock.unlock() }
return status
}
private func refreshIfStale() {
lock.lock()
let stale = readAt.map { Date().timeIntervalSince($0) > Self.maximumAge } ?? true
guard stale, !reading else {
lock.unlock()
return
}
reading = true
lock.unlock()
DispatchQueue.global(qos: .utility).async {
let answer = (try? developerModeStatus()) ?? [:]
self.lock.lock()
self.status = answer
self.readAt = Date()
self.reading = false
self.lock.unlock()
}
}
}
// MARK: - Device, Display, Audio, Network
extension GuestAPI {
private static let rotationLock = NSLock()
static func executeDevice(_ method: String, _ params: [String: Any]) throws -> [String: Any]? {
switch method {
case "device.info":
var info = try collectDeviceSnapshot()
info["jailbreak"] = jailbreakInfo()
info["network"] = networkInfo()
info["screen"] = screenInfo()
info["rotation"] = rotationInfo()
info["brightness"] = brightnessState()
info["volume"] = volume()
info["low_power_mode"] = (try? lowPowerMode()) ?? [:]
info["developer_mode"] = GuestDeveloperModeSnapshot.shared.current()
info["agent"] = ["binary_hash": binaryHash, "pid": getpid()]
info["device_name"] = deviceNameInfo()
return info
case "device.network":
return networkInfo()
case "network.ipv4.get":
return try networkIPv4(interface: optionalString(params, "interface") ?? "en0", set: nil)
case "network.ipv4.set":
return try networkIPv4(interface: optionalString(params, "interface") ?? "en0", set: params)
case "network.resolve":
let port = (params["port"] as? NSNumber).map(\.intValue)
let family: Int32 = switch optionalString(params, "family") {
case "ipv4": AF_INET
case "ipv6": AF_INET6
default: AF_UNSPEC
}
return try resolveHost(
string(params, "host"), family: family, port: port,
firstOnly: params["first_only"] as? Bool ?? false,
timeout: number(params, "timeout_ms", default: 5000) / 1000,
)
case "network.static_names.get":
return GuestStaticNames.shared.describe()
case "network.static_names.set":
return try GuestStaticNames.shared.set(params["entries"] as? [[String: Any]] ?? [])
case "network.hostname.get":
return try networkHostName(set: nil)
case "network.hostname.set":
// An absent or null name puts back the one vphoned replaced.
return try networkHostName(set: .some(params["local_host_name"] as? String))
case "device.name.get":
return deviceNameState()
case "device.name.set":
// An absent or null name gives the guest its own back.
let name = params["name"].flatMap { $0 is NSNull ? nil : $0 }
guard name == nil || name is String else {
throw GuestAPIError.invalidRequest("name must be a string or null")
}
return try setDeviceName(name as? String)
case "device.ioreg":
return try ioregistry(plane: optionalString(params, "plane") ?? "IOService")
case "device.input_devices":
return vp_hid_input_devices()
case "device.displays":
return ["displays": vp_display_probe()]
case "display.modes":
return vp_display_modes()
case "display.external.status":
return vp_external_display_status()
case "display.external.diagnostics":
return vp_external_display_diagnostics()
case "display.external.configure":
guard let enabled = params["enabled"] as? Bool else {
throw GuestAPIError.invalidRequest("enabled must be a boolean")
}
let width = params["width"] as? Int ?? 1920
let height = params["height"] as? Int ?? 1080
let result = vp_external_display_configure(enabled, width, height)
guard result["ok"] as? Bool == true else {
throw GuestAPIError.operationFailed(result["error"] as? String ?? "External display configuration failed")
}
return result
case "display.external.frame":
var error: NSString?
guard let data = vp_external_display_frame(&error) else {
throw GuestAPIError.operationFailed(error as String? ?? "External display capture failed")
}
return ["mime_type": "image/jpeg", "data": data.base64EncodedString()]
case "device.environment":
return try environmentReport()
case "device.basebin":
return try compareBaseBin(bundled: optionalString(params, "archive"))
case "display.brightness":
if params["value"] != nil {
try setBrightness(requiredNumber(params, "value"))
}
return brightnessState()
case "display.rotation":
rotationLock.lock()
defer { rotationLock.unlock() }
if let orientation = optionalString(params, "orientation"), vp_hinge_get()["enabled"] as? Bool == true {
return try setFoldableRotation(orientation)
}
if let orientation = optionalString(params, "orientation") {
// Preserve the physical pose across SpringBoard relaunches.
// CoreMotion's app pose provider cannot feed this HID sink.
let accelerometer = vp_accelerometer_get()
let previousPose = (accelerometer["degrees"] as? NSNumber).map { String($0.intValue) }
let publishesPose = accelerometer["provider_running"] as? Bool == true
let previousInterface = interfaceRotationDegrees()
if publishesPose {
guard vp_accelerometer_set_orientation(orientation) else {
throw GuestAPIError.operationFailed("Could not publish the accelerometer orientation")
}
}
do {
return try setRotation(orientation)
} catch {
// A refused rotation leaves the guest as it was. The pose
// is persisted, and a refused request still turns iPadOS's
// pointer: with the screen off, an upside-down request
// left the interface portrait and the pointer upside down,
// so the mouse ran backwards. Asking again for the
// interface's own orientation turns the pointer back.
if publishesPose, let previousPose {
_ = vp_accelerometer_set_orientation(previousPose)
}
if let previousInterface {
_ = try? setRotation(String(previousInterface))
}
throw error
}
}
var rotation = rotationInfo()
rotation["accelerometer"] = vp_accelerometer_get()
return rotation
case "display.orientation":
return interfaceOrientation()
case "display.posture":
return try setDevicePose(params)
case "display.pose":
return vp_device_pose_get()
case "display.rotation_lock":
guard let locked = params["locked"] as? Bool else {
throw GuestAPIError.invalidRequest("locked must be true or false")
}
return try setRotationLock(locked)
case "display.auto_lock":
return GuestLockScreenIdle.describe()
case "display.auto_lock.set":
guard let seconds = (params["seconds"] as? NSNumber)?.intValue else {
throw GuestAPIError.invalidRequest("seconds must be an integer")
}
return try GuestLockScreenIdle.setAutoLockSeconds(seconds)
case "screen.unlock":
return try GuestScreenUnlock.unlock(
passcode: optionalString(params, "passcode"),
timeout: number(params, "timeout", default: 10),
)
case "audio.volume":
let category = optionalString(params, "category") ?? "Audio/Video"
if params["value"] != nil {
return try setVolume(requiredNumber(params, "value"), category: category)
}
return ["volume": volume(category), "category": category]
case "audio.state":
return try audioState()
case "network.capture":
let seconds = number(params, "seconds", default: 5)
return try capturePackets(
seconds: seconds,
interface: optionalString(params, "interface") ?? "en0",
filter: optionalString(params, "filter"),
)
case "security.ssl_killswitch":
return sslKillswitchStatus()
case "diagnostics.self_test":
return try runSelfTests()
case "notify.post":
let state = try params["state"].map(notificationState)
return try postDarwinNotification(string(params, "name"), state: state)
case "notify.state":
return try darwinNotificationState(string(params, "name"))
default:
return nil
}
}
/// Reads SpringBoard directly; the UIScreen path can abort before display registration.
/// A foldable guest adds the angle its last fold settled at, so a host
/// polling the orientation also follows folds it did not ask for (Xcode's
/// DeviceHub).
private static func interfaceOrientation() -> [String: Any] {
var reply: [String: Any] = [
"degrees": interfaceRotationDegrees().map { $0 as Any } ?? NSNull(),
"source": "springboard",
]
if let angle = settledFoldAngle() {
reply["fold_angle"] = angle
// The window covers the panel while it is off: coming on, it
// shows its last frame from before until the guest draws again.
// The always-on Lock Screen keeps the panel on, so it stays shown.
reply["screen_off"] = GuestScreenUnlock.panelIsDark
}
return reply
}
/// The angle the virtual hinge holds, which every fold leaves it at; nil
/// on a guest whose hinge was never configured.
private static func settledFoldAngle() -> Double? {
let hinge = vp_hinge_get()
guard hinge["enabled"] as? Bool == true else { return nil }
return (hinge["angle"] as? NSNumber)?.doubleValue
}
// MARK: Device pose
/// CoreMotion's magic-pose values, by name. SpringBoard derives the hinge
/// angle from the hinge state with a five-entry table, so the hinge stops
/// at "open" (open, ambiguous); "transitioning" is not accepted.
static let poseHingeStates = ["ambiguous": 0, "closed": 1, "partially-open": 2, "open-flat": 3, "open": 4]
static let poseOrientations = [
"ambiguous": 0, "portrait": 1, "upside-down": 2, "landscape-left": 3,
"landscape-right": 4, "face-up": 5, "face-down": 6,
]
/// The angle a hinge state names, as Apple's screen states have it:
/// partially open is book (~100°). SpringBoard's own table for the pose
/// override says 90°, but with CoreMotion's relay it reads the hinge.
static let poseHingeAngles: [Double] = [0, 0, 100, 180, 180]
/// Apple's screen-state positions, from suiatool's help text shipped in
/// SpringBoardFoundation: closed, book (~100°) and open (a fraction of
/// the 180° range, or a name).
static let posePositions: [String: Double] = ["closed": 0, "book": 100, "open": 180]
/// Set a foldable guest's pose the way Apple's Duo tooling does. On a
/// guest whose CoreMotion has the foldable's capabilities the virtual
/// hinge's host controls carry the angle and orientation, locationd
/// relays them into CoreMotion, and SpringBoard reads its pose from there
/// as on a device; elsewhere SpringBoard's test-automation override sets
/// the pose beside the hinge. The official model is three screen states —
/// `position` `closed`, `book` (~100°) or `open`, or a fraction 0–1 of
/// the hinge's 180° — changed by a sweep from the current angle, which
/// SpringBoard's display tool service runs (`duration` seconds; default
/// the per-direction hand-fold time, opening faster than closing; 0 an
/// instant swap; `profile` `continuous` or `fade`, default SpringBoard's
/// own). The older `hinge` names still work and set the pose at once.
private static func setDevicePose(_ params: [String: Any]) throws -> [String: Any] {
func value(_ key: String, names: [String: Int], range: ClosedRange<Int>, default fallback: Int?) throws -> Int {
if let name = params[key] as? String {
guard let value = names[name.lowercased()] else {
throw GuestAPIError.invalidRequest("\(key) must be one of \(names.keys.sorted().joined(separator: ", "))")
}
return value
}
if let number = params[key] as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() {
guard range.contains(number.intValue), Double(number.intValue) == number.doubleValue else {
throw GuestAPIError.invalidRequest("\(key) must be an integer in \(range.lowerBound)...\(range.upperBound)")
}
return number.intValue
}
guard params[key] == nil, let fallback else { throw GuestAPIError.invalidRequest("\(key) is required") }
return fallback
}
var angle: Double?
var sweep = false
var durationMs = -1.0
var profile: String?
if let position = params["position"] {
let target: Double
switch position {
case let name as String:
guard let named = Self.posePositions[name.lowercased()] else {
throw GuestAPIError.invalidRequest("position must be closed, book, open, or a fraction in 0...1")
}
target = named
case let number as NSNumber where CFGetTypeID(number) != CFBooleanGetTypeID():
let fraction = number.doubleValue
guard fraction.isFinite, 0 ... 1 ~= fraction else {
throw GuestAPIError.invalidRequest("position must be closed, book, open, or a fraction in 0...1")
}
target = fraction * 180
default:
throw GuestAPIError.invalidRequest("position must be closed, book, open, or a fraction in 0...1")
}
angle = target
sweep = true
if let requested = params["duration"] as? NSNumber, CFGetTypeID(requested) != CFBooleanGetTypeID() {
let seconds = requested.doubleValue
guard seconds.isFinite, 0 ... 10 ~= seconds else {
throw GuestAPIError.invalidRequest("duration must be a number of seconds in 0...10")
}
durationMs = seconds * 1000
}
if let name = params["profile"] as? String {
profile = name.lowercased()
guard profile == "continuous" || profile == "fade" else {
throw GuestAPIError.invalidRequest("profile must be continuous or fade")
}
}
}
let hinge = try value("hinge", names: poseHingeStates, range: 0 ... 4, default: angle.map(hingeState(for:)))
let orientation = try value("orientation", names: poseOrientations, range: 0 ... 6, default: 1)
let tabletop = try value("tabletop", names: [:], range: 0 ... 10, default: 0)
if angle == nil {
angle = Self.poseHingeAngles[hinge]
if let requested = params["angle"] as? NSNumber, CFGetTypeID(requested) != CFBooleanGetTypeID() {
guard requested.doubleValue.isFinite, 0 ... 180 ~= requested.doubleValue else {
throw GuestAPIError.invalidRequest("angle must be a number in 0...180")
}
angle = requested.doubleValue
}
}
let relayed = vp_core_motion_hinge()
if relayed, orientation == 2 {
throw GuestAPIError.invalidRequest("the host controls have no upside-down orientation")
}
foldLock.lock()
defer { foldLock.unlock() }
GuestFoldPose.cancelStartupRestore()
var springBoardSwept = false
defer { GuestFoldPose.finishExplicitRequest(settledHinge: springBoardSwept ? Int32(hinge) : nil) }
let published: Bool
if relayed {
if let current = vp_hinge_get()["angle"] as? Double, hingeState(for: current) == 1, hingeState(for: angle!) != 1 {
// Opening a closed device wakes it; the hinge sensor's own wake
// flag does that on hardware, and the host controls cannot set
// it. SpringBoard's pose provider publishes a pose in motion only
// on display frames, so with the cover asleep the new angle would
// sit unpublished until the next wake. The screen is lit before
// the sweep starts.
GuestScreenUnlock.wakeDisplay()
}
// With the relay, the hinge is the pose.
published = sweep
? vp_hinge_sweep(angle!, durationMs, profile == "fade" ? 1 : 0, Int32(orientation))
: vp_hinge_set(angle!, Int32(orientation))
guard published else {
throw GuestAPIError.operationFailed("The virtual hinge did not take the pose")
}
} else {
// A sweep is SpringBoard's own, as Apple's tooling runs it: the
// display tool service moves SpringBoard's hinge pose and swaps
// displays on the way, keeping the device orientation unless one
// was asked for, and replies once the swap is done. The override is
// then left alone: it reaches SpringBoard even under the sweep's
// test lock and stands for 0, 90 or 180 degrees only, so book (100)
// would slide back to 90 and start a transition toward the cover.
// SpringBoard applies the next override against its current pose,
// so a later one still lands. The virtual hinge takes the end
// angle. Without the service the virtual hinge sweeps and the
// override jumps, as before.
if sweep {
springBoardSwept = try springBoardFold(
to: angle!, seconds: durationMs < 0 ? -1 : durationMs / 1000,
orientation: params["orientation"] == nil ? 0 : Int32(orientation),
profile: profile == "fade" ? 1 : profile == "continuous" ? 2 : 0,
)
}
guard springBoardSwept || vp_device_pose_set(Int32(orientation), Int32(hinge), Int32(tabletop)) else {
throw GuestAPIError.operationFailed("SpringBoardServices has no device pose override on this guest")
}
if params["orientation"] != nil { vp_device_orientation_publish(Int32(orientation)) }
// The pose has landed; the hinge half is published beside it, and
// its absence (no virtual hinge service on this guest) does not
// undo the pose.
published = sweep && !springBoardSwept
? vp_hinge_sweep(angle!, durationMs, profile == "fade" ? 1 : 0, 0)
: vp_hinge_set(angle!, 0)
}
var hingeHID = vp_hinge_get()
hingeHID["applied"] = published
var reply: [String: Any] = [
"hinge": hinge, "orientation": orientation, "tabletop": relayed ? NSNull() : tabletop,
"angle": angle!, "hinge_hid": hingeHID, "source": relayed ? "coremotion" : "test-automation",
]
if sweep {
reply["sweep"] = [
"duration_ms": durationMs,
"profile": profile ?? (springBoardSwept ? "springboard" : "continuous"),
"completed": springBoardSwept,
]
}
return reply
}
/// One posture request at a time: SpringBoard refuses a swap while another
/// is running, and the next request reads the hinge this one leaves.
private static let foldLock = NSLock()
/// Fold through SpringBoard's display tool service, waiting for it to
/// finish. True once SpringBoard ran the fold, false without the service
/// or a reply (the caller falls back to the override). SpringBoard answers
/// a swap it refuses (another one is running) at once and the same way as
/// a finished one, so a reply faster than any sweep that had to move is a
/// refusal, retried until SpringBoard is idle. The virtual hinge holds the
/// angle the last fold ended at, and takes the target as the fold starts:
/// DeviceHub reads it (through dtdeviceinfod) while its own model animates
/// to the target, and an old angle lingering through the sweep sent its
/// slider back there, folding the guest again. A fold that does not run
/// puts the old angle back.
private static func springBoardFold(to angle: Double, seconds: Double, orientation: Int32, profile: Int32) throws -> Bool {
let current = (vp_hinge_get()["angle"] as? NSNumber)?.doubleValue
let moves = current.map { abs($0 - angle) >= 1 } ?? true
var ran = false
if moves { _ = vp_hinge_set(angle, 0) }
defer { if moves, !ran, let current { _ = vp_hinge_set(current, 0) } }
let deadline = Date().addingTimeInterval(10 + max(seconds, 0))
while true {
let started = Date()
switch vp_display_swap(angle / 180, seconds, orientation, profile, max(1, deadline.timeIntervalSinceNow)) {
case -1, 0:
return false
default:
ran = !moves || seconds == 0 || Date().timeIntervalSince(started) >= 0.3
if ran { return true }
}
guard Date() < deadline else {
throw GuestAPIError.operationFailed("SpringBoard kept refusing the fold; another fold is still running")
}
Thread.sleep(forTimeInterval: 0.25)
}
}
/// A foldable guest turns with SpringBoard's device pose: each panel's
/// traits pipeline reads its own device orientation from the pose, so
/// neither the accelerometer nor the AssistiveTouch rotation icli drives
/// turns it. The rotation sets the pose orientation that gives the lit
/// panel the requested interface orientation — the inner panel is mounted
/// a quarter turn from the cover — and reads the interface back.
private static func setFoldableRotation(_ spec: String) throws -> [String: Any] {
let degreesByName = [
"0": 0, "portrait": 0, "90": 90, "landscape-left": 90, "left": 90, "180": 180, "upside-down": 180,
"portrait-upside-down": 180, "270": 270, "landscape-right": 270, "right": 270,
]
guard let degrees = degreesByName[spec.lowercased()] else {
throw GuestAPIError.invalidRequest("unknown rotation: \(spec)")
}
let pose = vp_device_pose_get()
guard pose["available"] as? Bool == true, let readHinge = (pose["hinge"] as? NSNumber)?.int32Value,
let tabletop = (pose["tabletop"] as? NSNumber)?.int32Value
else { throw GuestAPIError.operationFailed("SpringBoard's device pose is unavailable") }
// The pose readback does not follow SpringBoard's own folds; the
// virtual hinge holds where the last one ended.
let hinge = settledFoldAngle().map { Int32(hingeState(for: $0)) } ?? readHinge
// Pose orientations (poseOrientations) by interface degrees, measured
// on the cover (hinge closed) and on the inner panel (open).
let cover: [Int: Int32] = [0: 1, 90: 4, 180: 2, 270: 3]
let inner: [Int: Int32] = [0: 3, 90: 1, 180: 4, 270: 2]
let deviceOrientation = (hinge == 1 ? cover : inner)[degrees]!
// Partially open the override stands for 90° and slides the fold
// toward the cover; CoreMotion's relay reads the hinge instead.
guard hinge != 2 || vp_core_motion_hinge() else {
throw GuestAPIError.operationFailed("A partially open fold does not turn through the device pose.")
}
GuestFoldPose.cancelStartupRestore()
defer { GuestFoldPose.finishExplicitRequest() }
guard try turn(to: deviceOrientation, hinge: hinge, tabletop: tabletop, reaching: { $0 == degrees }) else {
throw GuestAPIError.operationFailed("The device did not apply the requested rotation.")
}
var info = rotationInfo()
info["requested"] = degrees
return info
}
/// A fold Xcode's DeviceHub asked for (GuestDeviceHubControl): the sweep
/// `display.posture` runs for a position, to `angle` degrees. With
/// CoreMotion's relay the hinge follows DeviceHub's values instead.
static func foldFromDeviceHub(angle: Double) throws {
_ = try setDevicePose(["position": NSNumber(value: min(max(angle, 0), 180) / 180)])
}
/// A device orientation DeviceHub's picker chose (1 portrait … 6 face
/// down): the pose override takes it with the hinge where it is. The
/// orientation DeviceHub reads back is published only once the interface
/// has turned, so a refused turn leaves its model where the guest is: an
/// iPhone19,4 scene refuses programmatic orientation (see
/// `display.rotation`), and in book the override, which means 90°, slides
/// the fold toward the cover, so book is left alone. With CoreMotion's
/// relay the host controls carry the orientation at any fold.
static func orientFromDeviceHub(_ deviceOrientation: Int32) throws {
foldLock.lock()
defer { foldLock.unlock() }
GuestFoldPose.cancelStartupRestore()
defer { GuestFoldPose.finishExplicitRequest() }
let hinge = settledFoldAngle().map { Int32(hingeState(for: $0)) } ??
(vp_device_pose_get()["hinge"] as? NSNumber)?.int32Value ?? 1
guard hinge != 2 || vp_core_motion_hinge() else {
throw GuestAPIError.operationFailed("a partially open fold does not turn through the pose override")
}
let before = interfaceRotationDegrees()
guard try turn(to: deviceOrientation, hinge: hinge, tabletop: 0, reaching: { $0 != before }) else {
throw GuestAPIError.operationFailed("SpringBoard did not turn the interface")
}
}
/// Set the device orientation and wait up to 3 s for the interface to
/// reach `turned`. With CoreMotion's relay the host controls carry it
/// with the angle the hinge holds, and CoreMotion turns it into each
/// panel's. Otherwise the pose override takes it; only once the interface
/// has turned is it published (DeviceHub's stand-in reads it), and a
/// refused one is put back, since SpringBoard keeps it and later folds
/// carry it.
private static func turn(to deviceOrientation: Int32, hinge: Int32, tabletop: Int32,
reaching turned: (Int?) -> Bool) throws -> Bool {
let relayed = vp_core_motion_hinge()
if relayed, deviceOrientation == 2 {
throw GuestAPIError.invalidRequest("the host controls have no upside-down orientation")
}
let previous = (vp_device_pose_get()["device_orientation"] as? NSNumber)?.int32Value
if relayed {
guard let angle = settledFoldAngle(), vp_hinge_set(angle, deviceOrientation) else {
throw GuestAPIError.operationFailed("The virtual hinge did not take the orientation")
}
} else {
guard vp_device_pose_set(deviceOrientation, hinge, tabletop) else {
throw GuestAPIError.operationFailed("SpringBoard refused the device pose")
}
}
for _ in 0 ..< 30 where !turned(interfaceRotationDegrees()) {
usleep(100_000)
}
guard turned(interfaceRotationDegrees()) else {
if !relayed, let previous, (1 ... 6).contains(previous), previous != deviceOrientation {
_ = vp_device_pose_set(previous, hinge, tabletop)
}
return false
}
if !relayed { vp_device_orientation_publish(deviceOrientation) }
return true
}
/// The hinge state a settled angle reports: closed under 5°, open flat
/// from 170°, partially open between — the bands Apple's recorded Duo
/// samples hold.
static func hingeState(for angle: Double) -> Int {
if angle < 5 { return 1 }
if angle >= 170 { return 3 }
return 2
}
private static func brightnessState() -> [String: Any] {
["value": brightness(), "auto": autoBrightness().map { $0 as Any } ?? NSNull()]
}
/// A notify(3) state is a full UInt64, beyond what a JSON double holds
/// exactly, so a decimal string is accepted as well as a number. A JSON
/// boolean also decodes as NSNumber and is refused.
private static func notificationState(_ value: Any) throws -> UInt64 {
let number = (value as? NSNumber).flatMap { CFGetTypeID($0) == CFBooleanGetTypeID() ? nil : $0 }
let text = (value as? String) ?? number?.stringValue
guard let text, let state = UInt64(text) else {
throw GuestAPIError.invalidRequest("state must be an unsigned 64-bit integer")
}
return state
}
}
// MARK: - Network configuration
extension GuestAPI {
/// Read, or with `set` write, the interface's IPv4 settings in configd's
/// network preferences. The host calls `set` after every connect to hold
/// the guest to the address in its manifest.
static func networkIPv4(interface: String, set params: [String: Any]?) throws -> [String: Any] {
var error: NSString?
let result = if let params {
vp_network_ipv4_set(interface, params, &error)
} else {
vp_network_ipv4_get(interface, &error)
}
guard let result = result as? [String: Any] else {
throw GuestAPIError.operationFailed(error.map(String.init) ?? "network configuration failed")
}
return result
}
/// Read the guest's mDNS name, or with `set` change it (`.some(nil)` puts
/// back the one vphoned replaced).
static func networkHostName(set name: String??) throws -> [String: Any] {
var error: NSString?
let result = if let name {
vp_network_hostname_set(name, &error)
} else {
vp_network_hostname_get(&error)
}
guard let result = result as? [String: Any] else {
throw GuestAPIError.operationFailed(error.map(String.init) ?? "host name change failed")
}
return result
}
}
// MARK: - Device name
/// The device name the host pins: what Xcode, devicectl and Finder show.
/// `libdevicename.dylib` in configd and lockdownd reads it from
/// `deviceNameConfigPath` (see `Research/Guest/device_name_pinning.md`):
/// configd publishes it as `Setup:/System`'s ComputerName and lockdownd refuses
/// every rename. The guest's own name stays in preferences.plist.
///
/// The file outlives a reboot, so configd's first publication at boot already
/// carries the name. A change applies at once: both daemons check the file on
/// every decision, and applying the preferences unchanged makes configd's
/// preferences monitor publish again.
extension GuestAPI {
/// Must match `VP_DEVICE_NAME_CONFIG_PATH` and `VP_DEVICE_NAME_CONFIG_KEY`
/// in `VPhoneGuestComponents/DeviceName/DeviceNamePolicy.h`.
static let deviceNameConfigPath = "/var/db/vphone/devicename.plist"
static let deviceNameConfigKey = "DeviceName"
/// What lockdownd posts after a rename; lockdown clients read the name again.
static let deviceNameChangedNotification = "com.apple.mobile.lockdown.device_name_changed"
/// `{name}`: the pinned name, or null when the guest shows its own.
static func deviceNameState() -> [String: Any] {
["name": storedDeviceName() ?? NSNull()]
}
/// Pin `name`, or with nil give the guest its own back. Returns the state
/// plus `changed` and `reboot_required`: lockdown readers (Finder,
/// `ideviceinfo`, `idevicename`) follow a change at once, but CoreDevice (Xcode,
/// `devicectl`) reads the name once per handshake and the DHCP lease keeps
/// the host name it was requested with, so both show the new name only
/// after the guest restarts. A clone of a template boots with the
/// template's pin until `vphone-vm` connects and sets its own.
static func setDeviceName(_ name: String?) throws -> [String: Any] {
if let name {
try validateDeviceName(name)
}
let changed = storedDeviceName() != name
if changed {
try writeDeviceName(name)
guard storedDeviceName() == name else {
throw GuestAPIError.operationFailed("\(deviceNameConfigPath) did not read back as written")
}
var error: NSString?
guard vp_preferences_apply(&error) else {
throw GuestAPIError.operationFailed(
"The name is stored but configd was not asked to publish it: \(error.map(String.init) ?? "apply failed")",
)
}
_ = try? postDarwinNotification(deviceNameChangedNotification, state: nil)
}
var state = deviceNameState()
state["changed"] = changed
state["reboot_required"] = changed
return state
}
/// For `device.info`: the pinned name, and the guest's own ComputerName in
/// configd's preferences, which a clone inherits from its template. Two
/// small file reads.
static func deviceNameInfo() -> [String: Any] {
let path = "/private/var/preferences/SystemConfiguration/preferences.plist"
let preferences = FileManager.default.contents(atPath: path).flatMap {
try? PropertyListSerialization.propertyList(from: $0, format: nil) as? [String: Any]
}
let system = (preferences?["System"] as? [String: Any])?["System"] as? [String: Any]
return [
"name": storedDeviceName() ?? NSNull(),
"own_name": system?["ComputerName"] as? String ?? NSNull(),
]
}
/// `GuestDeviceNameRule`: not blank, at most 255 UTF-8 bytes, no control
/// character.
private static func validateDeviceName(_ name: String) throws {
if let problem = GuestDeviceNameRule.problem(name) {
throw GuestAPIError.invalidRequest(problem)
}
}
private static func storedDeviceName() -> String? {
guard let data = FileManager.default.contents(atPath: deviceNameConfigPath),
let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
let name = plist[deviceNameConfigKey] as? String, !name.isEmpty
else { return nil }
return name
}
/// Replaces the file in one rename, which is what the hook's stamp check
/// expects, or removes it.
private static func writeDeviceName(_ name: String?) throws {
guard let name else {
if unlink(deviceNameConfigPath) != 0, errno != ENOENT {
throw GuestAPIError.operationFailed("Could not remove \(deviceNameConfigPath): \(String(cString: strerror(errno)))")
}
return
}
let directory = (deviceNameConfigPath as NSString).deletingLastPathComponent
do {
try FileManager.default.createDirectory(
atPath: directory,
withIntermediateDirectories: true,
attributes: [.posixPermissions: 0o755],
)
let data = try PropertyListSerialization.data(
fromPropertyList: [deviceNameConfigKey: name], format: .binary, options: 0,
)
try data.write(to: URL(fileURLWithPath: deviceNameConfigPath), options: .atomic)
} catch {
throw GuestAPIError.operationFailed("Could not write \(deviceNameConfigPath): \(error.localizedDescription)")
}
// World-readable: the hooks only ever read it.
chmod(deviceNameConfigPath, 0o644)
}
}
// MARK: - Name resolution
extension GuestAPI {
/// One `getaddrinfo` answer, kept as the raw socket address for the
/// connect test.
private struct ResolvedAddress {
let text: String
let family: Int32
let storage: Data
}
/// The results of a `getaddrinfo` that ran on another thread, which
/// `resolveHost` stops waiting for after its timeout.
private final class ResolutionResult: @unchecked Sendable {
private let lock = NSLock()
private var value: (status: Int32, addresses: [ResolvedAddress])?
func set(_ status: Int32, _ addresses: [ResolvedAddress]) {
lock.withLock { value = (status, addresses) }
}
func get() -> (status: Int32, addresses: [ResolvedAddress])? {
lock.withLock { value }
}
}
/// What the guest's own resolver makes of `host`: every address
/// `getaddrinfo` returns, in its order, and how long it took. With `port`,
/// each address is also connected to (two seconds each; only the first with
/// `first_only`, as a client that does not fall back would), reporting the
/// local address the guest used, which names the interface it went out of.
/// For diagnosing names that resolve slowly, or to an address the guest
/// cannot reach.
static func resolveHost(_ host: String, family: Int32, port: Int?, firstOnly: Bool, timeout: Double) throws -> [String: Any] {
let started = Date()
let result = ResolutionResult()
let finished = DispatchSemaphore(value: 0)
DispatchQueue.global(qos: .userInitiated).async {
var hints = addrinfo()
hints.ai_family = family
hints.ai_socktype = SOCK_STREAM
var list: UnsafeMutablePointer<addrinfo>?
let status = getaddrinfo(host, port.map(String.init), &hints, &list)
var addresses: [ResolvedAddress] = []
var entry = list
while let info = entry {
defer { entry = info.pointee.ai_next }
guard let address = info.pointee.ai_addr else { continue }
addresses.append(ResolvedAddress(
text: numericHost(address, length: info.pointee.ai_addrlen),
family: info.pointee.ai_family,
storage: Data(bytes: address, count: Int(info.pointee.ai_addrlen)),
))
}
if let list {
freeaddrinfo(list)
}
result.set(status, addresses)
finished.signal()
}
let elapsed = { Int(Date().timeIntervalSince(started) * 1000) }
guard finished.wait(timeout: .now() + max(timeout, 0.1)) == .success, let resolved = result.get() else {
return ["host": host, "status": "timeout", "elapsed_ms": elapsed()]
}
var reply: [String: Any] = ["host": host, "elapsed_ms": elapsed()]
guard resolved.status == 0 else {
reply["status"] = "error"
reply["error"] = String(cString: gai_strerror(resolved.status))
return reply
}
reply["status"] = "resolved"
reply["addresses"] = resolved.addresses.enumerated().map { index, address -> [String: Any] in
var item: [String: Any] = [
"address": address.text,
"family": address.family == AF_INET6 ? "ipv6" : "ipv4",
]
if port != nil, !firstOnly || index == 0 {
item.merge(connectTest(address), uniquingKeysWith: { $1 })
}
return item
}
return reply
}
private static func numericHost(_ address: UnsafePointer<sockaddr>, length: socklen_t) -> String {
var host = [CChar](repeating: 0, count: Int(NI_MAXHOST))
guard getnameinfo(address, length, &host, socklen_t(host.count), nil, 0, NI_NUMERICHOST) == 0 else { return "?" }
return String(decoding: host.prefix { $0 != 0 }.map { UInt8(bitPattern: $0) }, as: UTF8.self)
}
/// A non-blocking connect with a two-second limit.
private static func connectTest(_ address: ResolvedAddress) -> [String: Any] {
let started = Date()
let descriptor = socket(address.family, SOCK_STREAM, 0)
guard descriptor >= 0 else { return ["connect": "error", "connect_error": String(cString: strerror(errno))] }
defer { close(descriptor) }
_ = fcntl(descriptor, F_SETFL, fcntl(descriptor, F_GETFL, 0) | O_NONBLOCK)
let result = address.storage.withUnsafeBytes { raw in
connect(descriptor, raw.baseAddress!.assumingMemoryBound(to: sockaddr.self), socklen_t(raw.count))
}
var outcome: [String: Any] = [:]
if result == 0 || errno == EINPROGRESS {
var poller = pollfd(fd: descriptor, events: Int16(POLLOUT), revents: 0)
if poll(&poller, 1, 2000) == 1 {
var error: Int32 = 0
var length = socklen_t(MemoryLayout<Int32>.size)
_ = getsockopt(descriptor, SOL_SOCKET, SO_ERROR, &error, &length)
outcome["connect"] = error == 0 ? "connected" : "error"
if error != 0 {
outcome["connect_error"] = String(cString: strerror(error))
}
} else {
outcome["connect"] = "timeout"
}
} else {
outcome["connect"] = "error"
outcome["connect_error"] = String(cString: strerror(errno))
}
var local = sockaddr_storage()
var length = socklen_t(MemoryLayout<sockaddr_storage>.size)
let named = withUnsafeMutablePointer(to: &local) { pointer in
pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(descriptor, $0, &length) }
}
if named == 0 {
outcome["local"] = withUnsafePointer(to: &local) { pointer in
pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { numericHost($0, length: length) }
}
}
outcome["connect_ms"] = Int(Date().timeIntervalSince(started) * 1000)
return outcome
}
}